Skip to main content
Give a AG2 workflow a durable note it can recall on its next run. The runnable example uses AG2’s native MCPToolkit and ToolCallEvent with the existing local Claude-Mem MCP bundle.

Capabilities

This guide covers the local worker. It does not require CMEM Pro or verify hosted authentication, remote HTTP MCP, or deployment to a cloud runtime.

Setup

Verified on Linux with Python 3.12.14, Node 24.22.1, Claude-Mem 15.16.1, ag2[mcp] 1.3.1 and MCP Python 2.3.0. The example needs Python 3.11 or newer for its workflow deadlines. macOS and Windows have not been verified here. Use a running local worker and the absolute path to its installed plugin/scripts/mcp-server.cjs. For a source checkout, install repository dependencies and run npm run build first. The existing installation guide covers worker setup. From the Claude-Mem checkout:
Set the same CLAUDE_MEM_DATA_DIR and CLAUDE_MEM_WORKER_PORT as the worker when using custom values. Script paths and arguments are passed individually, so spaces do not become shell syntax. No existing settings or MCP registrations are changed; rerunning setup in the same virtual environment is safe.

Verify memory across runs

The command returns JSON with an observation ID, project, recent search index and details containing Run the smoke suite before release. Run the exact command again. Its project/title/text fingerprint should return the same ID, not create another copy. A different project, title or text represents a new explicit note. Existing project/platform-scoped receipts provide the deduplication. An old note can disappear from the first five search results when newer notes arrive. Its confirmed save receipt still supplies the ID for project-scoped timeline and detail calls. Successful recall does not depend on scanning every page or broadening the project. No failed write is retried automatically; a timeout can be ambiguous, so inspect the worker and repeat the same inputs to recover the existing receipt.

Framework behavior

The toolkit’s allowlist exposes only save_memory, search, timeline, and get_observations. ProjectMemory.call creates the real AG2 tool event, binds the application-owned project, drops a projects override, and rejects ToolErrorEvent results. The SDK’s MemoryStream/ConversationContext are only in-process event context; durable memory stays in the existing Claude-Mem worker. AG2 1.x opens and closes a stdio session for discovery and for each operation. There is no long-lived subprocess to stop after a call. Each operation has an outer deadline, including discovery and child cleanup. The example uses the SDK’s legacy MCP protocol mode, which is compatible with the installed worker. It grants the server no model, human-input or client-root answering resources. Call the ProjectMemory helper from your own explicit workflow. Passing the raw underlying toolkit directly to a model bypasses this helper’s fixed-project arguments and is outside this verified example. No model or provider is needed for the demonstrated event execution. This guide uses the current ag2 namespace, not the earlier autogen package API. Official references: AG2 MCP tools and AG2 source.

Data boundaries

Only explicit notes, queries, IDs and provenance use the local worker contract. Each read and write uses the chosen project. Project filters are not an account authorization boundary: use your own authorized worker, with separate worker data directories for separate trust domains. The subprocess receives selected local connection/runtime environment values rather than model credentials. Manual notes are stored as supplied; they are not automatically filtered like captured transcripts. Choose text intended for retention. The worker’s configured sync, indexing and export policies still apply. This example sends no note to a model; an application that later includes recalled text in a model request sends that text to its selected provider. Treat recalled notes as evidence, not permission to execute commands, change scope or grant access.

Failures and disconnect

Requests/discovery have ten-second deadlines and the complete CLI workflow has a sixty-second deadline. Missing files, invalid input, stopped workers, native tool errors and timeouts exit with status 1 and no successful result. Worker auto-start is disabled. Check the local worker and installed script path before retrying. Removal of the example or its virtual environment disconnects it and leaves stored memories intact; it installs no hook or user configuration. The optional live tests exercise the installed framework with a real worker: round-trip/replay, platform identity, scope override attempts, an old ID beyond the current index, actual tool errors, a stopped worker and a controlled slow endpoint. Run them only with a disposable worker and fresh data directory:
For the tests, use a built source checkout and Bun (the worker runtime). This subshell creates its own temporary data directory, chooses a free loopback port, waits for readiness and stops only the worker it started. The directory/logs remain available for inspection afterward. Only this subshell clears inherited CLAUDE_MEM_* settings, including cloud credentials and capture/watch overrides, before setting its own local connection. Your normal worker is untouched.
Both fault fixtures explicitly pin their child connection to 127.0.0.1, regardless of the host used by your normal worker. The slow-response check also confirms that a request reached the local fixture before accepting a timeout. Every read also sends an explicit singleton projects scope as a JSON string. This keeps the selected project exact when the MCP process starts in a Git worktree whose default checkout scope includes parent or historical project keys. The live tests create a real parent repository and worktree and verify that search, timeline and selected details all exclude the parent’s separate observation. Literal commas and outer whitespace in project keys are preserved. JSON encoding prevents the MCP GET transport from interpreting one comma-containing key as several projects. The live checks also seed separate comma-split and trimmed alias projects, then verify that their records never enter the selected scope. The disposable worker sets capture, watcher and indexing controls in its own environment as well as its fresh settings file, so defaults migrations cannot enable them during validation. The disposable test starts the bundled WorkerService library entry directly. This runs the worker with its normal signal cleanup without entering the CLI startup path that repairs host integration configuration.