McpWorkbench 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,autogen-ext[mcp] 0.7.5 and MCP Python 1.30.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:
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 containingRun 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
MemoryWorkbench subclasses the native workbench to expose only save_memory,
search, timeline, and get_observations. Every invocation replaces any
supplied project with the application-owned project and drops a projects
override. call_text checks AutoGen’s native ToolResult.is_error before using
the result. The context manager starts and stops the MCP actor and subprocess.
Keep the workbench’s async with scope open while using it as the workbench
of your existing AutoGen AssistantAgent. This guide verifies the tool workflow,
not a model choosing tools; your application still chooses its model and write
approval policy. This example does not serialize its custom scoped workbench.
The MCP pin is deliberate: AutoGen 0.7.5 uses the MCP 1.x client API. Installing
MCP 2.x alongside this release breaks its imports. Use a separate environment
instead of changing the MCP dependency of another application.
Official references: AutoGen MCP workbench and
workbench/tool guidance.
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:CLAUDE_MEM_* settings, including cloud credentials and capture/watch overrides,
before setting its own local connection. Your normal worker is untouched.
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.
