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.mdindex 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 theregression 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 CLIsubcommands, MCP tools, config keys, a new agent harness or LLMprovider); major = breaking (on-disk format without migration, removeddiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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; notool-call id in Droid payloads. `setup-agent --agent droid` prints thehook 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`, ordiff --git a/README.md b/README.mdindex 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.mdindex 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 plistSee [`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 companiondiff --git a/docs/design-client-sdk.md b/docs/design-client-sdk.mdindex 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 distributionThe server's distribution channels are built from the root Cargo workspace and@@ -178,8 +189,9 @@ release.### 3.1 Client surfaceOne 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`.```tsimport { 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 taxonomyAll 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 seamwould let an older server ignore `expectedPageId` as an unknown argument andturn 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 theenvironment, 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 useradd-human` and `ai-memory api-key add` ([users.md](users.md)), so tests run atboth 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 whoowns 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 schemasnapshot 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 aseam into core](companion-crates.md#when-to-move-a-seam-into-core), each shouldwait 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.mdindex 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 contexbetween executions. Native lifecycle hooks are optional. A tool that also hostsan 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 scopeConnect to `/mcp` using Streamable HTTP. The default transport is stateless: