Skip to content

The SDKs store the Claude API memory tool's files as Loom documents - #736

Open
zlareb1 wants to merge 3 commits into
mainfrom
feat/sdk-claude-memory-tool
Open

zlareb1 wants to merge 3 commits into
mainfrom
feat/sdk-claude-memory-tool

Conversation

@zlareb1

@zlareb1 zlareb1 commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Changelog category (leave one):

  • New Feature

Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes):

The Python and TypeScript SDKs run the Claude API memory tool's commands against Loom: the files Claude keeps under /memories are Loom documents, shared by every agent of the namespace and found by knowledge.search (pip install 'clickhouse-loom[claude-memory]'; @clickhouse/loom/integrations/claude-memory).

Why

The Claude API memory tool (memory_20250818) leaves storage to the application: the model sends view, create, str_replace, insert, delete and rename commands on paths under /memories, and the SDKs ship base classes to implement them (BetaAbstractMemoryTool / BetaAsyncAbstractMemoryTool in anthropic, betaMemoryTool with MemoryToolHandlers in @anthropic-ai/sdk). Their reference backend writes local files, so a Claude app's memory sits on one host and one agent. This PR implements those interfaces over Loom, so the memory tool's files live in the user's Loom deployment, every agent of the namespace reads the same files, and Loom's document search finds what they say. No store, vector database or cache is added.

Design (interfaces read from anthropic 2.8.0 and @anthropic-ai/sdk 1.8.0):

  • Files are documents, not memories. A memory file is text the model edits in place. Written through memory.set, two files with the same text would merge into one row and a near-identical file would be flagged as a conflict, since every searchable memory type goes through the write-time conflict check; a file store must never do either. Loom's documents plane fits a file: knowledge.upsert replaces a document by URI, knowledge.get returns its exact text (checked against a running server: whitespace, blank lines and trailing newlines come back byte for byte), knowledge.bulk_delete removes documents, and knowledge.search chunks and finds them.
  • Paths. /memories/<path> is the document loom-memory://<store>/memories/<path>, tagged claude-memory:<store>. Directories are the paths' prefixes; view of a directory lists the store's documents (knowledge.list by the tag, paged) two levels deep. store (default default) is one path segment: one tree per application, or per user. Every path must be /memories or under it after . and .. are resolved over the whole path (as POSIX normpath: /memories/a/../../memories/b is /memories/b in both SDKs), or the command is refused before Loom is called (the SDK's reference also accepts /memoriesX; this does not).
  • Answers. Both SDKs answer each command with the same text: the text and refusals the Python SDK's local memory tool uses (line-numbered views, the str_replace snippet, the insert range error, "already exists", "does not exist"), except that a directory view lists paths without sizes, since a document's size is not listed. The TypeScript SDK's own local tool words a few answers differently; one wording across both Loom SDKs keeps a store's behaviour the same from either. Hidden names (a segment starting with .) are left out at every level. An empty old_str is refused (counting empty matches would hang in JavaScript), and create is refused on a path that is a directory. A refusal is the SDK's ToolError, which the tool runner returns to the model as an error result.
  • Edits read the document and write it back (str_replace, insert); rename copies each file under the old path to the new one, then deletes the old; a failure partway leaves the copies made so far (the docs say so). Deletes go out 500 URIs a call, knowledge.bulk_delete's cap. Two agents editing one file at once keep the later write, as the SDK's local tool does; knowledge.upsert has no compare-and-set.
  • Python has both bases: AsyncLoomMemoryTool over a loom.Agent (async tool runner) and LoomMemoryTool over a loom.SyncAgent (sync runner); each refuses the other agent kind. The command logic is shared pure functions; the two classes only differ in awaiting the client.
  • TypeScript: loomMemoryHandlers(agent, { store }) returns MemoryToolHandlers, and loomMemoryTool(agent, { store }, extras) wraps them in betaMemoryTool, passing extras (such as cache_control) through, as the Python classes pass their keyword arguments to the base. Both SDKs read and write the same documents.
  • Scope. A store is not a boundary: documents are namespace-scoped, so every reader of the namespace reads every store. The docs say to give each user their own namespace when users must not read each other's files.
  • Packaging: clickhouse-loom[claude-memory] pins anthropic>=2.8,<3 (2.8 has the async base) and joins SDK_ADAPTER_EXTRAS; anthropic joins the root mypy overrides, since the SDK gate runs without the extra. @anthropic-ai/sdk is an optional peer dependency (>=1.8.0 <2.0.0, dev-pinned to 1.8.0), with its own export entry, build entry, README section and dist test.

Scope and risk

SDK-only: two modules, an extra, a peer dependency, docs. No server, wire or schema change; documents are already covered by erasure. uv.lock is unchanged; sdk/typescript/package-lock.json adds @anthropic-ai/sdk 1.8.0 as a dev dependency.

Compatibility, rollout and rollback

  • Wire: none.
  • Operator steps: none.
  • Rollback: reverting removes the modules, the extra and the peer dependency.

Tests

  • sdk/python/tests/test_claude_memory.py through make test-sdk-adapter-claude-memory (28 tests, each command test run on both the async and the sync tool; mypy --strict on the module): the classes are the SDK's memory tool bases and declare memory_20250818; create then view with line numbers and a range, and create refused when the file exists; a directory view two levels deep across list pages, hidden files left out; str_replace of one occurrence, refused for none or many; insert and its range; delete of a file or a directory (/p is not a prefix of /pq); rename of a file or a directory and its refusals; every path kept under /memories (/memoriesx, ../) with no call to Loom, and a/../../memories/b accepted; an empty old_str refused; nested hidden files left out; create on a directory refused; 501 files deleted as 500 + 1; a store sees only its own files; bad stores and the wrong agent kind refused; the import error names the extra; a real loom.Agent posts knowledge.get and knowledge.upsert with the URI and tag.
  • The same tests pass with SDK_ADAPTERS_RESOLUTION=lowest-direct on Python 3.11 (anthropic 2.8.0).
  • sdk/typescript/src/integrations/claude-memory.test.ts (10 tests, through a real Agent over a fetch stub): the same commands, refusals, paging, stores and path resolution, the empty old_str, nested hidden files, create on a directory, the batched delete, extras passed through, and a replacement text with $& kept literal. The TS SDK's own gates: biome check, tsc --noEmit, vitest run (356 passed), check:readme, check:version, and check:dist (build, the dist exports test with the new subpath, publint, attw).
  • tests/integration/test_sdk_claude_memory_tool.py against a local server (fake embedder): a file created, edited, inserted into, viewed, found by knowledge.search, renamed into a directory, hidden from another store, and deleted, with the document read back after each step. 1 passed with anthropic installed; without it the module skips, as in CI's integration jobs.
  • make format lint; the unit tests that name the integrations, the extras, the framework docs, doc links and public copy (978 passed).

AI assistance in the code (leave one; writing this description with AI is fine):

  • AI-generated (an agent wrote most of the diff): Claude Code. Checked: the memory tool bases, command types and the SDKs' local reference implementation (anthropic 2.8.0 _beta_builtin_memory_tool.py, @anthropic-ai/sdk 1.8.0 helpers/beta/memory), and the tools against a running Loom.

  • I can explain every line of this diff and how it interacts with the rest of Loom.

Checklist

  • make format-check, make lint, make typecheck and make test-unit pass (locally the named unit tests; the full suite in CI's pytest unit parts); the integration suite passes if server behaviour changed.
  • Generated files are regenerated in this PR, not by hand: the SDK op tables, docs/reference/configuration.md and the docs/reference/ tables (python scripts/codegen/docs_reference.py), the reach manifest, schemas/schema.sql (make schema-dump) and the Codex plugin copies (python3 scripts/codegen/agent_plugin_sync.py).
  • A new migration is additive and numbered after the latest on main; no merged migration is edited.
  • A behaviour change to any file a plugin ships (hooks/, lib/, bin/, skills/, .mcp.json, the Codex plugin-defaults.json) bumps both plugin manifests' version, and no other open PR uses that version.
  • The frontend builds (npm --prefix frontend run build) and its tests pass, if frontend/ changed.
  • Docs under docs/ describe the system as it now is, and this description names any operator steps and wire changes.
  • Repository text has no dates, people, host names, internal namespaces, ticket or decision numbers; the history goes in this description (tests/unit/test_public_copy.py).
  • Commits are signed off (git commit -s), as CONTRIBUTING.md asks.

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
}

function under(paths: string[], directory: string): string[] {
const prefix = `${directory.replace(/\/+$/, "")}/`;

/** A directory view, two levels deep, as the SDK's local memory tool lists one (no sizes). */
function listing(shown: string, directory: string, paths: string[]): string {
const base = directory.replace(/\/+$/, "");
`Invalid \`insert_line\` parameter: ${line}. It should be within the range [0, ${lines.length}].`,
);
}
lines.splice(line, 0, insert.replace(/\n+$/, ""));
zlareb1 and others added 2 commits November 16, 2026 08:09
…eletes 500 a call, hides nested hidden files, and resolves paths alike in both SDKs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
…ed rename leaves

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants