infinicon

give your ai agents unbounded context.

Infinicon is a memory SDK + reference server for AI agents. Install @infinicon/sdk in your app and run @infinicon/server for storage and retrieval.

Specs and ADRs in docs/ remain the source of truth for behavior.

Install

Agent (client):

npm install @infinicon/sdk

Memory server (requires Bun):

npx @infinicon/server
# listens on http://localhost:8787

Or deploy to Render:

import { openMemory } from "@infinicon/sdk"

const memory = openMemory()
await memory.remember("user prefers dark mode")
const prior = await memory.recall("theme preference")

Support

If Infinicon helps your project, consider supporting development:

☕ Support via Razorpay

(GitHub also shows a Sponsor heart on the repo via .github/FUNDING.yml.)

Start Here

Building an agent? → examples/simple-chat.ts + @infinicon/sdk

• Vision
• Glossary
• Architecture overview
• Reference runtime
• Plugin host architecture
• Roadmap
• Specifications index
• Architecture decision records

Repository Layout

src/
  runtime/          # canonical memory runtime (MemoryRuntimeService + adapters)
  transport/        # HTTP routing layer
  server.ts         # Bun server entrypoint
packages/
  sdk/              # @infinicon/sdk — published npm client
  server/           # @infinicon/server — published reference server
  core-types/       # @infinicon/core-types — spec-aligned contracts
  plugin-host/      # plugin registration and lifecycle host
examples/
  simple-chat.ts    # one-file agent demo (start here)
  agent-chat/       # fuller SDK example with recall + consolidation
contracts/          # machine-readable OpenAPI + JSON schemas
docs/               # specs, ADRs, devops
tests/              # runtime, server, contract tests

Canonical Subsystems

Subsystem	Location
SDK (start here)	packages/sdk/ → @infinicon/sdk
Server	packages/server/ → @infinicon/server
Runtime	src/runtime/service.ts
Server source	src/server.ts + src/transport/httpServer.ts
Core types	packages/core-types/
Plugin host	packages/plugin-host/
Storage adapters	src/runtime/adapters/
API contracts	contracts/

Run Locally

bun test
npx @infinicon/server   # or: bun run dev (from repo clone)
bun run example:simple  # minimal one-file agent (recommended to start)
bun run example:agent   # full agent-chat example

Copy env for the agent example:

cp examples/agent-chat/.env.example examples/agent-chat/.env

Server default: http://localhost:8787

API Endpoints

• GET /health
• POST /v0/ingest
• POST /v0/query
• POST /v0/hydrate
• POST /v0/assemble-context
• POST /v0/tombstone
• POST /v0/consolidate
• POST /v0/subscribe
• POST /v0/get-job
• GET /v0/jobs/{jobId}

Verification

bun run verify
python3 scripts/spec_integrity_check.py
python3 contracts/scripts/validate_contracts.py
node tests/validate-examples.js

Machine-Readable Contracts

Draft machine-readable artifacts derived from v0 prose specs live under contracts/.

• OpenAPI: contracts/openapi/memory-api.v0.json
• JSON Schemas: contracts/schemas/*
• Fixtures: contracts/fixtures/*

Storage manifests and adapter capability descriptors live under docs/contracts/.

Prose specs in docs/specs/*.md remain normative. Update prose first, then contracts.

Packages

• @infinicon/sdk: TypeScript client for the memory API
• @infinicon/server: reference memory server (npx @infinicon/server)
• @infinicon/core-types: spec-aligned TypeScript contracts, validators, and JSON schemas
• @infinicon/plugin-host: plugin registration host (bundled into server)

Examples

Command	What
bun run example:simple	One-file chat agent (examples/simple-chat.ts)
bun run example:agent	Full example with recall + consolidation (examples/agent-chat/)
JSON fixtures	examples/memory-api/ etc. — spec samples, not runnable apps

See examples/README.md.

Reference server notes

• Default storage is in-memory (lost on server restart). Set DATABASE_URL for Postgres.
• Retrieval in the reference stack is lexical unless you plug in embedder/ranker plugins.
• Optional Bearer auth via INFINICON_API_KEY on the server.
• docs/devops/deployment.md for Render/production.

Publishing (maintainers)

Packages publish to npm on GitHub Release or manual workflow dispatch.

1. Bump version in packages/core-types/package.json, packages/sdk/package.json, and packages/server/package.json
2. Add a GitHub repo secret NPM_TOKEN (npm granular access token with publish scope)
3. Create a release tag (e.g. v0.1.1) — triggers .github/workflows/publish-npm.yml

bun run build:packages   # local dry run before release