MCPServerStdio with Claude-Mem’s existing MCP server.
What this connection does
This guide covers the local worker. CMEM Pro, hosted server authentication,
and remote HTTP MCP are not required or verified here. A paid model run is a
separate step in your application.
Prerequisites
Verified on Linux with Python 3.12.14, Node 24.22.1,openai-agents 0.24.0,
MCP Python 2.3.0, and Claude-Mem 15.16.1. Python 3.11 or newer is required for
the example’s workflow deadline. Other operating systems have not been
verified for this example.
Use a running local Claude-Mem worker and the absolute path to its installed
plugin/scripts/mcp-server.cjs. The command accepts that path directly; it does
not depend on a particular plugin cache version. For a source checkout, install
the repository dependencies and run npm run build first. The existing
installation guide covers worker setup.
From the Claude-Mem checkout:
CLAUDE_MEM_DATA_DIR or CLAUDE_MEM_WORKER_PORT, set
the same values for the command. Paths and project names containing spaces are
passed as individual arguments, without a shell command assembled from them.
The example leaves worker settings and other MCP registrations alone.
Verify the result
Successful output includes a selected observation ID, its project, and the note:sourceFingerprint receipt returns the same observation instead of creating a
second copy. Changing the project, title or text represents a new explicit note.
The output includes a recent project index. An older repeated note may have
fallen off that page; the confirmed save receipt still supplies its ID for the
timeline and detail requests, so the workflow does not need to scan every page.
The example does not retry writes automatically. If a call times out after a
write, rerun the exact same input to check its existing receipt.
Every read carries the chosen project. That separates project results, but a
local worker connection is not an account authorization boundary. Use only your
own local worker. The example saves exactly the supplied note through the
existing manual-memory API; it never collects excluded project transcripts or
copies conversation history. Choose text that is intended to be retained.
The worker’s configured storage, cloud sync and export destinations still apply
to saved notes. This script itself sends no note to an OpenAI model. If your
application later sends recalled details to a model, those details leave the
machine through that model request. Treat retrieved notes as evidence, not as
instructions to execute commands or grant access.
Use it in an agent
memory_server() returns the SDK’s native MCP server object and filters its tool
list to save_memory, search, timeline and get_observations. Keep the context
manager open while passing it to an Agent(mcp_servers=[server]). Your agent
application must choose its model, credentials, project scope and write approval
policy explicitly. The included deterministic workflow exercises the real SDK
and MCP transport; it does not test a model deciding when to call tools.
See the official OpenAI Agents SDK MCP guide
and MCP server API.
Failures and disconnect
Requests have a 10-second SDK timeout and the complete CLI workflow has a 60-second deadline.--timeout changes the request timeout and must be positive
and finite. A missing MCP file, stopped worker, rejected tool call or deadline
exits with status 1; it does not print a successful result. Check the installed
path and the worker’s status before rerunning. Worker auto-start is disabled for
this explicit workflow so a failed connection does not change running services.
The context manager closes its MCP child when the workflow ends. Stop calling
the example, remove it from your own agent, or delete the example virtual
environment to disconnect. No configuration entry needs to be removed, and
disconnecting does not erase saved memory.
The optional test_memory_workflow.py checks the real SDK and worker, including
replay, project isolation, attribution, rejected input and unavailable or slow
workers. Run it only against a disposable worker with a 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.
