ReMe/integrations/claude_code

ReMe memory for Claude Code

中文说明

Start a ReMe service, then install the ReMe plugin in Claude Code. This is the supported integration for this host. The plugin bundles automatic recall, completed-turn recording, MCP tools, and the reme-memory skill in one installation. ReMe manages durable memory and consolidation in your workspace.

The plugin and its marketplace are maintained in integrations/claude_code/ and installed from this checkout. Keep the ReMe service running while using the plugin.

Start ReMe → Install the ReMe plugin → Use memory in Claude Code

Requirements

• Python 3.11+ available as python3 in the host's environment, with FastMCP >= 3.1 (included with ReMe).
• A current Claude Code version supporting plugin command hooks, async, and Stop last_assistant_message.
• A running ReMe HTTP service exposing search, auto_memory, and health_check, with MCP enabled.
• A working model configuration on the ReMe server for memory extraction. Default BM25 recall does not need embeddings.

1. Start ReMe

pip install "reme-ai[core]"
reme start workspace_dir=/absolute/path/to/workspace service.backend=http

The default endpoint is http://127.0.0.1:2333, with MCP at /mcp. Keep the unauthenticated HTTP service on loopback or behind a protected proxy. Different workspaces isolate different memory scopes; sharing one workspace between hosts is intentional cross-agent recall.

2. Install the plugin

In Claude Code, using an absolute path to this checkout:

/plugin marketplace add /absolute/path/to/ReMe/integrations/claude_code
/plugin install reme@reme-marketplace

Restart Claude Code or reload the installed plugin, then open a new conversation. The installation loads the bundled hooks, MCP connection, and skill together. Reinstall or reload the plugin after updates.

3. Use memory in Claude Code

In a new conversation, ask “Check whether ReMe is available.” The installed plugin's tools check the running service; /mcp shows the plugin's connection status. Then use Claude Code normally: the plugin recalls relevant memory before prompts and records completed turns in batches of five. For an explicit query, ask “What did we decide about Project Juniper? Cite the memory sources.”

Automatic recording sends completed user/assistant text to the configured ReMe service. Set auto_memory to false for recall-only use.

Optional configuration

The default service address works immediately after plugin installation. Create a configuration file only when you want to change the defaults below.

Edit the user configuration file directly to change addresses and behavior. Plugin upgrades preserve this file, and only overrides need to be saved.

Settings live at ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/reme/config.json. For a new file, copy the bundled example; edit an existing file in place:

mkdir -p "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/reme"
cp integrations/claude_code/reme/config.example.json "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/reme/config.json"

Option	Default	Meaning
mcp_url	http://127.0.0.1:2333/mcp	MCP address; removing the trailing /mcp gives the default HTTP base for hooks
api_url	Empty string	Optional HTTP Job API base; required for custom MCP paths
auto_recall	true	Search before a user prompt
auto_memory	true	Queue and submit completed turns; false also disables retries
recall_limit	5	Search result limit
recall_min_score	0	Minimum recall score
recall_timeout	5	Foreground HTTP timeout in seconds, at most 10
request_timeout	600	Memory-write and MCP request timeout in seconds, at most 600
memory_interval	5	Completed turns per batch; use 1 for immediate per-turn writes
shutdown_timeout	2	Total best-effort exit drain budget in seconds, at most 2
context_max_chars	8000	Maximum recalled payload characters
timezone	Asia/Shanghai	Daily batch timezone; match the ReMe workspace

For example, use another port and disable automatic recording:

{
  "mcp_url": "http://127.0.0.1:2444/mcp",
  "auto_memory": false,
  "auto_recall": true,
  "memory_interval": 1
}

Both MCP and hooks read addresses from this user configuration. Hooks pick up edits on their next invocation. After changing an address or the MCP timeout, reconnect MCP or restart the host so the existing MCP process also reads the new settings. No source edits, cache edits, or reinstall are needed. For a custom MCP path such as https://memory.example.com/tools, also set api_url to the HTTP Job API base, for example https://memory.example.com/reme.

Unknown fields and invalid values fail validation; hooks skip work and log hook_failed instead of falling back to another service. Disabling auto_memory stops automatic capture and retries while preserving pending batches; explicit MCP tools remain available. Changing the service address never sends old pending conversations to the new service. Remove a field to restore its default.

The plugin uses a host-managed stdio process to forward MCP. Start the host with a python3 environment containing FastMCP. If ReMe runs on another machine or in another Python environment, run python3 -m pip install "fastmcp>=3.1" in the host environment. Hooks use only the standard library.

Lifecycle and failure behavior

• UserPromptSubmit calls search synchronously with a short timeout. Results are bounded and wrapped in <reme-context> as untrusted historical evidence. A failure does not reject the prompt.
• Native asynchronous Stop hooks extract only the completed user/final-assistant text from the hook's local transcript, then submit auto_memory batches through the JSON Job API. Tool output, reasoning, and injected ReMe context are excluded. The server does not need access to host files.
• Session and message IDs are stable and host-scoped. Repeated Stops are deduplicated. Per-session process locks serialize writes; batches never mix dates. Subagent events and hook continuations are excluded. No extra background daemon, package download, or ReMe process is started.
• Queues and acknowledgement receipts live under the host's reme/queue/, separate from the plugin cache and namespaced by endpoint. A failed or timed-out write stays queued. SessionStart retries pending work in the background; SessionEnd attempts a short, synchronous drain.
• Shutdown and delivery are best-effort. A host killed before the Stop hook captures a turn can lose that turn. A lost HTTP acknowledgement can cause a retry; stable message IDs prevent duplicate source messages, but memory extraction is at least once, not exactly once. Short residual batches survive for the next session when shutdown has insufficient time.
• Queue files contain source conversation text; retain them until delivery completes. Logs in reme/hooks.log contain event/error types only. Disabling auto_memory retains pending files.
• Daily auto_dream consolidation remains owned by the ReMe service. Unlike OpenClaw's long-lived Gateway adapter, these short-lived hook processes do not run their own scheduler.

Verify and troubleshoot

1. In Claude Code, ask the installed ReMe plugin to check the connection; confirm its status in /mcp.
2. For a quick test, set memory_interval to 1, then start a new conversation and ask the agent to remember a synthetic fact, such as “Project Juniper reviews are on Thursday.”
3. Wait for the write and inspect reme/hooks.log for memory_saved and the ReMe workspace's daily/.
4. Start a separate conversation and ask for that fact. Confirm recall is from ReMe, with source paths.

The installed plugin provides both automatic memory and explicit search/read and health checks. If its tools are missing, check that the plugin is installed and enabled, the service is running, and service.jobs exposes the required jobs. If its hooks do not load, use a host version supporting the plugin requirements and reinstall or reload the plugin.

Capture currently reads Claude JSONL user/assistant records with UUIDs. The hook requires transcript_path and last_assistant_message. Missing or unsupported transcripts are skipped rather than guessed. Check capture_skipped or hook_failed events when recall works but recording does not.

Migration from the previous Claude Code plugin

Version 0.2 replaces the detached Stop-only auto_memory_cc client with automatic recall and client-side completed-turn capture via auto_memory. The existing server job auto_memory_cc remains available. Existing session/claude_code/ transcripts and notes are preserved; new source messages use ReMe's standard {session_dir}/dialog/claude-code-<hash>.jsonl files and namespaced IDs. The plugin does not replay older conversations. Remove any manually installed duplicate Stop hook. Logs move from the plugin's logs/ directory to the host's reme/hooks.log.

For end-to-end checks, keep the session open until memory_saved appears. A short claude -p process can exit before its asynchronous hook receives the write acknowledgement; the next session retries captured work. A Markdown note alone does not prove that the queue was acknowledged.

Source and validation

Run pytest tests/unit/test_coding_agent_plugins.py -v from the ReMe checkout. Tests isolate host state and mock service calls. Native hook behavior is described in the Claude Code hook reference. ReMe is developed at agentscope-ai/ReMe under Apache-2.0.