Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: document the TypeScript SDK and record the design decisions

AkitaOnRails0a52c8e780fb
diff --git a/AGENTS.md b/AGENTS.md
index 1a9cd49e..621f4116 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -214,6 +214,8 @@ companions/ai-memory-wikisync/ team-wiki git sync through the public MCP tools;
companions/ai-memory-macos/ Swift menu bar wrapper; NOT a root workspace member —
`swift test --package-path companions/ai-memory-macos`
and `./companions/ai-memory-macos/build.sh`.
+companions/ai-memory-ts/ optional TypeScript client SDK (npm, Node 22+); NOT a workspace
+ member and never shipped with the server.
hooks/ per-agent lifecycle hook bundles (shell/native).
bin/ host wrapper scripts (`ai-memory`, `deploy`, `release`).
install.sh two-command native install, step one (release asset).
@@ -301,6 +303,13 @@ covers the same tests, slower, no tiers.
`swift test --package-path companions/ai-memory-macos`
(plus `./companions/ai-memory-macos/build.sh` to stage `AI Memory.app`).
Root `--workspace` commands do not cover it.
+- Run the TypeScript SDK separately, from `companions/ai-memory-ts`:
+ `npm ci --ignore-scripts`, `npm run check` (typecheck, unit tests, schema
+ and generated-docs checks, TypeDoc) and
+ `AI_MEMORY_BIN=../../target/debug/ai-memory npm run test:integration`
+ (real server, schema drift test, examples). npm tooling and its lockfile
+ stay inside that directory; nothing in the core workspace or the server
+ distribution depends on Node.
### Platform notes
@@ -676,7 +685,13 @@ Additional boundary rules:
- **MCP tool surface changes** require updating `MEMORY_INSTRUCTIONS`,
`ai_memory_core::SNIPPET_BODY`, README/docs tool references, and the
regression tests asserting every tool appears in both prompt surfaces.
- The tool count is currently 23 (see `docs/ARCHITECTURE.md`).
+ The tool count is currently 23 (see `docs/ARCHITECTURE.md`). They also
+ update the TypeScript SDK in `companions/ai-memory-ts` in the same change:
+ the schema snapshot (`npm run schema:update`), the wrapper or its
+ classification in `src/coverage.ts`, types, tests and docs. The SDK's
+ schema drift test in CI fails until they do. Changes to the `/api/v1`
+ routes the SDK wraps follow the same rule, enforced by its integration
+ tests.
- **Semantic versioning:** patch = fixes; minor = additive (new CLI
subcommands, MCP tools, config keys, a new agent harness or LLM
provider); major = breaking (on-disk format without migration, removed
diff --git a/CHANGELOG.md b/CHANGELOG.md
index aa01d8f2..0bd7e3ef 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -371,6 +371,25 @@ and [0.x](docs/changelog/0.x.md).
applies to them: verified against the Droid 0.240.0 tool schemas; no
tool-call id in Droid payloads. `setup-agent --agent droid` prints the
hook config and `uninstall` removes both entries. (#1240)
+- Added an optional TypeScript client SDK in `companions/ai-memory-ts` for
+ programs that are not coding-agent harnesses: custom agents, bots, editor
+ and app extensions, scripts and CI jobs. `AiMemoryClient` wraps the page,
+ query, status, recent, handoff, message, briefing, explore,
+ session-observation and feedback tools, the read-only `/api/v1` routes (with
+ cursor paging and `ETag` revalidation) and `GET /identity`, with typed
+ results, a typed error taxonomy and scope checks before any request.
+ `pages.update` reads a page, applies a change and writes it back guarded by
+ `expectedPageId`, keeping the page's metadata. A separate
+ `ai-memory-ts/admin` entry point covers checkpoints, page restore and
+ session or project purges, which default to a dry run and need both
+ `dryRun: false` and `confirm: true` to delete. The SDK has no runtime
+ dependencies, needs Node 22 and a 3.0.0 server, and is built from a checkout
+ for now; it is not published to npm and is never part of the server's
+ tarballs, Docker image, Homebrew, AUR, RPM or Nix packages, which
+ `scripts/check-native-packaging.sh` now enforces. CI runs it against the
+ server built from the same commit, including a schema drift test that fails
+ when an MCP tool changes without an SDK update. See
+ `companions/ai-memory-ts/README.md` and `docs/design-client-sdk.md`. (#1165)
### Changed
- Changed scoped `/api/v1/search` (a single `workspace` + `project`, or
diff --git a/README.md b/README.md
index 3ca1502a..871478aa 100644
--- a/README.md
+++ b/README.md
@@ -637,7 +637,7 @@ diagram, crate breakdown, schema notes, and invariants.
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. |
| [`docs/design-decisions.md`](docs/design-decisions.md) | The full v1 spec. |
| [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md) | Protocol and acceptance bar for adding managed resume, transcript import, and startup context delivery to another harness. |
-| [`docs/companion-crates.md`](docs/companion-crates.md) | Optional companion projects: the [importer](companions/ai-memory-importer), [external lifecycle relay](companions/ai-memory-relay), and [team-wiki sync](companions/ai-memory-wikisync). |
+| [`docs/companion-crates.md`](docs/companion-crates.md) | Optional companion projects: the [importer](companions/ai-memory-importer), [external lifecycle relay](companions/ai-memory-relay), [team-wiki sync](companions/ai-memory-wikisync) and the [TypeScript client SDK](companions/ai-memory-ts). |
| [`docs/external-lifecycle.md`](docs/external-lifecycle.md) | External lifecycle producers: per-execution native capture suppression, preserved handoffs, batch ingestion and stable retry identity. |
| [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: scheduled review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. |
diff --git a/docs/companion-crates.md b/docs/companion-crates.md
index 42c8da37..2f7a7e85 100644
--- a/docs/companion-crates.md
+++ b/docs/companion-crates.md
@@ -424,16 +424,35 @@ override is written only into the rendered LaunchAgent plist
See [`docs/macos.md`](macos.md#scenario-d-menu-bar-app).
-## Planned: client SDK
-
-Issue #1165 asks for a typed client for programs that are not coding-agent
-harnesses: custom agents and bots, editor and app extensions (RFC #1166) and
-automation scripts. The plan is a TypeScript companion at
-`companions/ai-memory-ts`, with Python as a later decision. It wraps the
-existing MCP tools, `/api/v1` reads and `GET /identity`, adds no core surface,
-and is never bundled in the server's tarballs, Docker image, AUR, Homebrew or
-Nix packages. Nothing is implemented yet; the design, test plan and the
-maintainer decisions per phase are in [design-client-sdk.md](design-client-sdk.md).
+## `ai-memory-ts`: TypeScript client SDK
+
+Typed client for programs that are not coding-agent harnesses (issue #1165):
+custom agents and bots, editor and app extensions (RFC #1166) and automation
+scripts. It lives at [`companions/ai-memory-ts`](../companions/ai-memory-ts),
+has no runtime dependencies, and talks to ai-memory only through the public
+MCP tools at `/mcp`, the read-only `/api/v1` routes, `GET /identity` and, from
+the separate `ai-memory-ts/admin` entry point, the root-only `/admin/*`
+lifecycle routes. It adds no core surface. Python is a later, separate
+decision.
+
+It is not part of the server distribution: release tarballs, Homebrew, the
+Docker image, AUR, RPM and Nix never build or ship it, and
+`scripts/check-native-packaging.sh` fails if one of their build files starts
+referencing it. It is unpublished until the maintainer picks the npm name and
+owner. Build and test it separately:
+
+```bash
+cd companions/ai-memory-ts
+npm ci --ignore-scripts
+npm run check # typecheck, unit, schema, docs
+AI_MEMORY_BIN=../../target/debug/ai-memory npm run test:integration
+```
+
+CI runs its integration tests, schema drift test and examples against the
+server built in the `test` job, so a change to an MCP tool schema fails until
+the SDK's `schema/tools.json` is updated. The design, test plan and decisions
+are in [design-client-sdk.md](design-client-sdk.md); usage is in the package
+[README](../companions/ai-memory-ts/README.md).
## `ai-memory-web-editor`: browser chat/editor companion
diff --git a/docs/design-client-sdk.md b/docs/design-client-sdk.md
index 113f3ff5..3f25831e 100644
--- a/docs/design-client-sdk.md
+++ b/docs/design-client-sdk.md
@@ -1,12 +1,15 @@
# Design: an optional client SDK (#1165)
-**Status: planned, parked (2026-10-10) — implementation waits for the maintainer's go.**
+**Status: phases 1 to 3 implemented for 3.0 (2026-10-13) in
+`companions/ai-memory-ts`. Phase 4 (publishing) is prepared but disabled until
+decision D1. Phase 5 (Python) is out of scope.**
This document plans a typed client library for programs that call ai-memory
-over HTTP. Nothing here is implemented. It records the shape the maintainer
-would accept (issue #1165, owner comments), the evidence from the repository
-behind each choice, and the decisions that remain the maintainer's. It does not
-approve any new core endpoint, MCP tool or wire field.
+over HTTP. It records the shape the maintainer accepted (issue #1165, owner
+comments), the evidence from the repository behind each choice, and the
+decisions taken or still pending (§9). It does not approve any new core
+endpoint, MCP tool or wire field. Where the implementation settled a detail
+the plan left open, the section says so in an "Implemented" note.
## 1. Goals, non-goals and audience
@@ -121,6 +124,14 @@ companions/ai-memory-ts/
└── integration/
```
+Implemented: the shipped layout adds `src/core.ts` (shared tool-call
+plumbing), `src/decode.ts` (result decoders), `src/coverage.ts` (the tool
+classification table the drift test, the static schema check and the README
+generator read), `src/admin.ts` (the `ai-memory-ts/admin` entry point),
+`test/support/` (the real-server harness, the scripted `fetch` and schema
+normalization) and `scripts/` (`schema:update`, `schema:check`,
+`docs:generate`/`docs:check`).
+
### 2.2 Never part of the server distribution
The server's distribution channels are built from the root Cargo workspace and
@@ -178,8 +189,9 @@ release.
### 3.1 Client surface
One entry class with namespaces that mirror the server's concepts. The first
-release targets Node 22 and newer and also runs on Deno and Bun through
-standard `fetch`; callers on other runtimes inject their own `fetch`.
+release targets Node 22 and newer. Deno and Bun work through standard
+`fetch` in a manual smoke run but are not tested in CI (§9, Q8); callers on other runtimes inject their own
+`fetch`.
```ts
import { AiMemoryClient } from "ai-memory-ts"; // final name: decision D1
@@ -337,6 +349,12 @@ Examples of result types:
- `query` returns `{ hits }`, where a superseded version has
`superseded: true` when `includeSuperseded` was set.
+Implemented: result fields are camelCase and every result also carries the
+server's decoded JSON in `raw`, so fields a newer server adds are reachable
+without an SDK update, and user-supplied keys (frontmatter, relation maps)
+are never renamed. A global query puts its cross-project hits in `hits` with
+`workspace` and `project` set (the server sends them as `global_hits`).
+
### 3.4 Error taxonomy
All errors extend `AiMemoryError`, which carries a stable `code` string for
@@ -345,6 +363,7 @@ callers who prefer a switch over `instanceof`.
| Class | When | Notable fields |
|---|---|---|
| `ConfigError` | invalid server URL, URL with credentials, query or fragment; token over plain HTTP to a non-loopback host without `allowInsecureHttp` | none |
+| `ArgumentError` | an argument fails validation before sending: `pages.read` without exactly one of `path` and `query`, `expectedPageId` with `createOnly`, an admin purge without both flags | none |
| `ScopeError` | missing, partial or empty scope; scope combined with `global` | none |
| `TransportError` | DNS, connection refused, TLS, refused redirect | `cause` (sanitized) |
| `TimeoutError` | the client's own deadline expired | `uncertain` |
@@ -407,6 +426,11 @@ header or a request body.
into a duplicate or a lost claim.
- JSON-RPC ids increase per client instance.
+Implemented: response bodies are read with a size cap (32 MiB by default,
+`maxResponseBytes`). Server text that reaches an error is also scrubbed of the
+token before the 300-character preview, so a hostile server that echoes the
+`Authorization` header cannot get it into a log.
+
### 3.6 Protocol version and server compatibility
- The client sends `initialize` with the newest MCP protocol version it
@@ -421,7 +445,7 @@ header or a request body.
incremental `recent` shipped in 2.6.0. A floor below the precondition seam
would let an older server ignore `expectedPageId` as an unknown argument and
turn a guarded write into an unconditional one, which is why wikisync
- refuses servers older than 3.0 (`ensure_conditional_writes` in
+ refuses servers without that seam (`ensure_conditional_writes` in
`companions/ai-memory-wikisync/src/mcp.rs`).
- `capabilities()` runs `initialize` (server name, version, protocol version),
`tools/list` (tool names and input-schema property names) and
@@ -503,6 +527,11 @@ admin dry run. Each example takes its server URL and token from the
environment, and the integration job runs every one against the CI server
(§5.5).
+Implemented: the quickstart confirms the connection with `identity()` and
+calls `status()` after the first write, because reads never create a project
+and `status()` on a fresh scope fails closed. Running the examples in CI
+caught this.
+
### 4.5 Troubleshooting
`docs/troubleshooting.md` maps each error class to causes and fixes:
@@ -570,6 +599,15 @@ deadline. Setup creates a DB user and an `aim_` key through `ai-memory user
add-human` and `ai-memory api-key add` ([users.md](users.md)), so tests run at
both root and user level. Each test uses its own workspace and project.
+Implemented: each test file starts its own server (`test/support/server.ts`),
+so files run in parallel without sharing state. The server gets a synthetic
+root token and token pepper and an environment built from scratch, so no
+`AI_MEMORY_*` variable from the developer's shell reaches it. Sessions for the
+observation and purge tests are seeded through `POST /hook/batch`. Handoff
+ownership is tested between two DB users, because handoffs created with the
+root token have no owner. Extra servers cover `--enable-api` off and a
+stateful server under `--base-path /wiki`.
+
Every public method has at least one success test and its failure paths:
- write, read, query, delete; `create_only` on an existing page and a stale
@@ -718,6 +756,8 @@ Estimates assume one developer familiar with TypeScript and the repository.
### Phase 1: first slice (about 6 to 8 working days)
+Status: implemented.
+
Files:
- `companions/ai-memory-ts/` with the layout in §2.1, `"private": true`.
@@ -745,12 +785,16 @@ and confirm the 3.0.0 floor.
### Phase 2: reads and messaging (about 4 to 5 days)
+Status: implemented.
+
`api.*` with pagination and ETag, `recent`, `messages.*`, `briefing`,
`explore`, `observations`, `feedback`; matching tests, examples and docs.
Decision: none beyond phase 1, unless the maintainer wants to trim the list.
### Phase 3: `AdminClient` (about 3 to 4 days)
+Status: implemented (D3 approved).
+
`checkpoints`, `restorePage`, `purgeSession`, `purgeProject`, behind
`ai-memory-ts/admin`, with the dry-run defaults and the admin security tests.
Decision D3: whether the SDK should ship admin methods at all, or leave
@@ -758,6 +802,11 @@ lifecycle operations to the CLI and the documented HTTP recipes.
### Phase 4: publishing (about 1 to 2 days, then ongoing)
+Status: prepared, disabled. `.github/workflows/sdk-ts-publish.yml` publishes
+with npm trusted publishing and `--provenance`, but its only trigger is a
+manual dispatch and it fails while `package.json` is `"private": true`.
+Enabling it is the checklist in that file's header, after D1.
+
The publish workflow with trusted publishing and provenance, the package name,
hosted API reference. Decision D1: publish to npm, under which name, and who
owns the npm account and responds to security reports for the package.
@@ -765,6 +814,8 @@ Publishing is a long-term maintenance commitment (owner comment on #1165).
### Phase 5: Python client (about 7 to 10 days)
+Status: out of scope for 3.0.
+
`companions/ai-memory-py/` with the same surface, standard library only
(`urllib.request`, `json`), the same error taxonomy, sharing the schema
snapshot and the integration harness. Decision D2: build it, and whether to
@@ -786,26 +837,50 @@ None is required for phases 1 to 5. Per [companion-crates.md, When to move a
seam into core](companion-crates.md#when-to-move-a-seam-into-core), each should
wait until shipped SDK callers show the need.
-## 9. Open questions
-
-- Q1 (package name). The directory is `ai-memory-ts`; the npm name needs
- an availability check and the maintainer's choice (D1).
-- Q2 (base paths). wikisync refuses servers behind a path prefix. Should the
- SDK accept `https://host/prefix` for reverse-proxy deployments, and how would
- CI test it?
-- Q3 (marker file). Should a helper read `.ai-memory.toml` when both names
- are declared, or should scope always come from the caller?
-- Q4 (non-project writes). `memory_write_page` accepts a `scope` of
- `global` or `profile`. Should the SDK expose those writes in phase 2, given
- that they affect every project?
-- Q5 (admission rejections). Is a typed `AdmissionRejectedError` worth a
- core change to add `data.reason`?
-- Q6 (session attribution). `memory_write_page` accepts `session_id`. Is
- there an SDK caller that needs to attribute writes to a captured
- session, or does that belong to the relay and harness integrations?
-- Q7 (read-modify-write helper). A `pages.update(path, change)` helper that
- reads, applies a change and writes with `expectedPageId` would remove a
- common mistake (a write clears omitted metadata). Should it ship in phase 1,
- or wait for a caller?
-- Q8 (Node floor). Node 22 is the proposed minimum. Should CI also cover
- Deno and Bun, or document them as untested?
+## 9. Decisions
+
+Decisions taken for the 3.0 implementation, each the smallest choice that
+fits the plan:
+
+- D1 (publishing, package name and owner): **pending.** The directory and the
+ placeholder package name are `ai-memory-ts`. The package stays
+ `"private": true` and the publish workflow stays dispatch-only and refuses to
+ run until the maintainer picks the npm name and the account that owns it and
+ answers security reports.
+- D2 (Python): out of scope for 3.0.
+- D3 (admin methods): approved; shipped behind `ai-memory-ts/admin`.
+- D4 (core changes): none made. The SDK uses only existing routes and tools.
+- Q1 (package name): see D1.
+- Q2 (base paths): **supported.** The server already moves every route under
+ `--base-path`, so the SDK accepts `https://host/prefix` and appends routes
+ to it. The integration suite starts a server with `--base-path /wiki` and
+ checks MCP, `/identity` and `/api/v1` under the prefix, with the unprefixed
+ URL as the control. Dot segments in page paths and scope names are refused
+ before sending, so a path cannot climb out of the prefix.
+- Q3 (marker file): **scope always comes from the caller.** No helper reads
+ `.ai-memory.toml`. A library that reads files from its working directory
+ surprises callers in servers and bundles, and the static-client rule wants
+ the caller's code to show which project it writes to.
+- Q4 (non-project writes): **not wrapped.** `pages.write` always sends a
+ project scope. Writes with `scope: "global"` or `"profile"` reach every
+ project, so they stay explicit through `callTool` until a caller needs them.
+- Q5 (admission rejections): **no core change.** They stay `RpcError`
+ (`-32603`) until the server marks them with a `data.reason`.
+- Q6 (session attribution): **not wrapped.** `session_id` on writes belongs to
+ the relay and harness integrations; `callTool` covers the rare SDK caller.
+- Q7 (read-modify-write helper): **shipped** as
+ `pages.update(path, change)`. It reads the page, carries its metadata over
+ (title, tier, tags, pinned, kind, entities, abstract, relations, TTL), applies
+ the change (`null` clears a field), and writes with the read version as
+ `expectedPageId`. One attempt and no retry: a concurrent change raises
+ `PreconditionFailedError` and writes nothing. The page must exist.
+- Q8 (runtimes): **Node 22 floor**, tested on Node 22 and 24 in CI. Bun and
+ Deno are documented as untested in CI; the SDK uses only standard `fetch`,
+ `AbortSignal`, `TextDecoder` and `URL`, and a manual smoke run against a
+ real server passed on Bun 1.4.3 and Deno 2.9.6. Adding them to CI would need
+ a second test runner, since the suite uses `node:test`.
+- Server floor: **3.0.0** (§3.6).
+- Lint: no ESLint, to keep development dependencies to `typescript`,
+ `@types/node` and `typedoc`. Strict `tsc` (unused locals and parameters,
+ exact optional properties, no unchecked index access) and TypeDoc with
+ warnings as errors stand in for it.
diff --git a/docs/programmatic-memory.md b/docs/programmatic-memory.md
index 188edb74..4af3324a 100644
--- a/docs/programmatic-memory.md
+++ b/docs/programmatic-memory.md
@@ -4,6 +4,16 @@ Any tool can use ai-memory over MCP to save knowledge, search it and pass contex
between executions. Native lifecycle hooks are optional. A tool that also hosts
an agent harness can send that harness's lifecycle events through HTTP.
+## Use the TypeScript SDK
+
+Programs in TypeScript or JavaScript can use the optional client SDK in
+[`companions/ai-memory-ts`](../companions/ai-memory-ts/README.md) instead of
+building JSON-RPC requests by hand. It wraps the calls on this page with typed
+results and typed errors, checks scope before sending, and keeps the
+conditional-write, handoff and lifecycle rules below. It is built from a
+checkout for now. The `curl` recipes on this page remain the
+language-neutral reference.
+
## Connect and choose a scope
Connect to `/mcp` using Streamable HTTP. The default transport is stateless: