Agents

Agents should use memory through a narrow, auditable interface. ZMem can bind several agent clients to one project memory store without copying chat transcripts between them.

Connect This Project

To connect one current agent session, run:

cd your-project
zmem connect codex --label current-chat

ZMem initializes the workspace if needed, configures that agent host, and prints one copy-ready memory.session_attach instruction. Reload the client if it has not picked up the MCP entry, then paste the instruction into that chat. The invitation is agent-bound, single-use, and expires after ten minutes by default.

To configure several clients against the same project memory store in one pass, use:

cd your-project
zmem setup codex claude-code hermes --summary-only
zmem status --summary-only

zmem setup initializes the project memory files and writes workspace-bound MCP entries for clients ZMem can configure directly. Codex and Claude Code need a restart or reload after setup. For Hermes, Cursor, OpenClaw, and generic MCP clients, setup writes a project-local export and tells you exactly what still needs to be imported.

All selected clients point to the same absolute .zerker/memory.sqlite path. They share approved project memory, review state, and receipts. They do not share raw transcripts, hidden reasoning, or every message by default.

Activate a Chat

Setup configures the agent host, not a chat that is already running. Reload Codex or Claude Code, open a new chat if the current one does not refresh its tools, then say:

Use the zerker-memory tools for this project. Request relevant memory before work.

The MCP server supplies the operating instructions after it connects. .zerker/AGENT_PROMPT.md contains the same durable guidance for clients that need it added to project instructions manually.

To make another current connector visible as a named live session, use zmem connect <agent> or open zmem ui and use Agent Memory Network. Choose the agent, label the chat, optionally add Room context, then create and copy the one-time instruction.

The lower-level invitation command remains available when the client is already configured:

zmem session invite --agent codex --label release-chat --summary-only

Paste the instruction into that chat. The agent calls memory.session_attach with the one-time code. The console shows the attachment as live or idle and can detach it without deleting stored memory. The terminal equivalents are:

zmem session connections --summary-only
zmem ui

The code is stored only as a hash, expires after ten minutes by default, is bound to the configured agent identity, and cannot be replayed. If the client exposes a stable chat id, the agent may include it as client_session_id; that value is explicitly client-asserted. Otherwise ZMem proves the MCP process attachment without pretending it knows the host's visible chat id.

An invitation can carry a Room id for context, but it never grants Room membership. Gateway remains authoritative for Room access.

What ZMem Knows

Generated MCP entries bind a host identity such as codex or claude-code. Each running MCP process also gets a connection provenance id. That lets ZMem reject another agent name supplied in a tool call and trace proposals back to a connector process.

A connection id is not guaranteed to be the visible chat id. Agent hosts decide whether an MCP process belongs to one chat, one window, or a longer-lived application session. When a workflow needs a durable named session, use the session lifecycle commands or pass the host's stable session id with the memory proposal.

zmem doctor --agent codex --agent claude-code verifies that each entry points to this project's exact database and policy. It no longer treats an entry for another workspace as ready.

See The Shared Memory Network

zmem ui

The local console separates three facts that are easy to conflate:

• configured: the client points to this exact database and policy;
• observed: ZMem has provenance from a real memory write by that agent;
• active: configured and observed are both true;
• live: a named connector consumed a one-time invitation and contacted ZMem recently.

This means a config file merely sitting on disk is not presented as proof that a chat used ZMem. The same view shows observed sessions, source provenance, shared-store alignment, and the latest transfer package. Unknown frameworks that write through generic MCP still appear by their recorded agent identity.

Session controls in this view use the same durable local invitation and attachment ledger as the CLI and MCP tools. They do not grant Room membership, elevate an agent to operator authority, or copy chat transcripts into memory.

Manual Clients

For clients that do not accept direct config writes:

zmem agent pack --summary-only
zmem agent checklist openclaw
zmem agent checklist generic

The pack includes the exact export path, doctor command, prompt path, snippet fallback, embedded server JSON, and proof smoke.

Use zmem agent install <preset> when you need the low-level single-client command or a custom --config-path.

MCP Server

zmem --db .zerker/memory.sqlite mcp --profile agent

Generated configs use this narrow agent profile and bind the selected agent identity. It exposes memory.session_attach, memory.session_status, memory.propose, memory.inject, memory.why, and memory.verify. The session tools can only bind the current MCP process with a trusted one-time invitation; they cannot mint membership or modify memory. The remaining tools let an agent request governed memory and propose reviewable memory, but not write trusted memory, approve its own proposal, inspect quarantine, or restore state.

Use examples/mcp_config.example.json as the reference shape for MCP-capable clients. Review and maintenance belong in the local CLI or UI:

zmem queue
zmem promote <memory-id>
zmem reject <memory-id> --reason "unsafe or stale"
zmem revoke <memory-id> --reason "no longer valid"
zmem ui

A full --profile operator MCP server exists for a trusted local review client. Do not attach it to an autonomous or untrusted agent.

Agent Rule

Agents should request governed memory before acting, use only the returned memories as durable context, and keep the action id when memory shaped work. The point is not just recall; it is inspectable recall.