Connect an agent over MCP, watch it keep a promise across sessions, and see every tool, command and endpoint it can use. The commands and outputs on this page come from a real Meaning Memory 3.20.0 deployment.
Read the documentation → Quickstart, guides, concepts and the full reference.
meaning-memory init generates the agent's configuration, its consolidation bridge
and a README. This example uses the file backend, which needs no database. For production,
pass --backend postgres --dsn …, and pick an extraction model with
--provider openai | anthropic | ollama.
# 1. Install the engine with the MCP server (the wheel ships in your customer kit)
pip install "meaning_memory-<version>-py3-none-any.whl[mcp]"
# 2. Scaffold an agent workspace: config, consolidation bridge, README
meaning-memory init --agent-id support-bot --backend file \
--workspace /srv/support-bot-mm --non-interactive
# 3. Check the environment
meaning-memory doctor --profile quickstart --agent support-bot \
--workspace /srv/support-bot-mm --config-dir /srv/support-bot-mm
# 15 OK, 1 warning
# The one warning (cron-runs-log) looks for a scheduled-job log
# that a new install doesn't have. It is safe to ignore.The MCP server will not start without an access policy, so a production deployment never runs open by accident. A single agent with private memory looks like this:
scope_auth.yaml# /srv/scope_auth.yaml: which memory scopes each agent may read and write
version: 1
agents:
support-bot:
allowed_scope_groups: [agent:support-bot]
groups:
agent:support-bot: { backfill_policy: forward_only }mm-mcp.
The server speaks standard MCP over stdio. MM_ALLOW_INTERNAL=1 lets the agent write;
leave it out for a read-only agent.
Add this to .mcp.json (Claude Code) or .cursor/mcp.json (Cursor).
{
"mcpServers": {
"meaning-memory": {
"command": "mm-mcp",
"env": {
"MM_AGENT": "support-bot",
"MM_ACTOR": "support-bot",
"MM_BACKEND": "file",
"MM_WORKSPACE": "/srv/support-bot-mm",
"MM_CONFIG_DIR": "/srv/support-bot-mm",
"MM_SCOPE_AUTH_CONFIG": "/srv/scope_auth.yaml",
"MM_ALLOW_INTERNAL": "1"
}
}
}
}Add the server under mcp_servers in your Hermes config.yaml.
mcp_servers:
meaning-memory:
command: mm-mcp
env:
MM_AGENT: support-bot
MM_ACTOR: support-bot
MM_BACKEND: file
MM_WORKSPACE: /srv/support-bot-mm
MM_CONFIG_DIR: /srv/support-bot-mm
MM_SCOPE_AUTH_CONFIG: /srv/scope_auth.yaml
MM_ALLOW_INTERNAL: "1"Load the tools through the LangChain MCP adapter and hand them to any LangGraph agent. Give it the few tools it needs rather than all 53.
Pythonfrom langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
client = MultiServerMCPClient({
"meaning-memory": {
"transport": "stdio",
"command": "mm-mcp",
"args": [],
"env": {
"MM_AGENT": "support-bot",
"MM_ACTOR": "support-bot",
"MM_BACKEND": "file",
"MM_WORKSPACE": "/srv/support-bot-mm",
"MM_CONFIG_DIR": "/srv/support-bot-mm",
"MM_SCOPE_AUTH_CONFIG": "/srv/scope_auth.yaml",
"MM_ALLOW_INTERNAL": "1",
},
}
})
wanted = {"mm_remember", "mm_search", "mm_due_commitments"}
tools = [t for t in await client.get_tools() if t.name in wanted]
agent = create_react_agent(
model, # any LangChain chat model
tools,
prompt="Store promises with mm_remember as commitments with a due_at date. "
"Answer questions about promises with mm_due_commitments.",
)The agent stores a commitment in one session. A later session starts with no chat history and still knows what is owed. The tool responses below are real output, lightly trimmed.
Remember this for later: I promised Dana at Acme I'd send her the updated pricing sheet by November 7.
mm_remember({
"text": "Send Dana at Acme the updated pricing sheet.",
"memory_type": "commitment",
"commitment_status": "pending",
"due_at": "2026-11-07"
})**Remembered** — `c9f737d32b583106`
**Pipeline state:** stored in ledger. Keyword search returns immediately via `mm_search`.What did I promise Acme, and by when?
mm_due_commitments({})
## Commitments (due / overdue)
> Open obligations tracked by Meaning Memory, surfaced by due date and never hidden by significance decay. Close with `mm_close_commitment`.
📅 Scheduled
- Send Dana at Acme the updated pricing sheet. — due 2026-11-07 · c9f737d32b583106You promised Dana at Acme that you'd send her the updated pricing sheet by November 7, 2026.
When memories become searchable. Commitments, and anything written through the REST
API, are searchable immediately. Other memories written over MCP are queued and become searchable
when the consolidation job drains the queue. The customer kit ships a systemd timer for it, and
init prints the setup commands.
On the file backend, mm_search matches your query as a phrase, so short keyword queries
work best; the Postgres backend adds hybrid keyword and semantic retrieval.
Most agents need only a handful: mm_remember, mm_search and
mm_due_commitments cover the session above. The rest are there when the job calls for them.
Write memories one at a time or in bulk, and pull them back ranked by significance.
mm_remember | Store a memory: semantic, episodic, procedural or commitment. |
mm_bulk_remember | Load a seed corpus (up to 1,000 items per call), such as a product catalog or FAQ. |
mm_search | Search memories; returns significance-ranked results ready for context injection. |
mm_session_recall | Read back the working buffer for one exact session. |
Promises an agent makes, tracked to a due date and closed explicitly.
mm_due_commitments | List open commitments by due date, overdue flagged. |
mm_close_commitment | Close a commitment as completed, cancelled or failed. |
mm_reopen_commitment | Undo a close. |
mm_satisfy_commitment | Mark the current occurrence of a recurring duty done and move to the next. |
mm_waive_commitment | Deliberately skip the current occurrence of a recurring duty. |
mm_promote_commitment | Turn a suggested commitment into one the agent owns. |
mm_dismiss_commitment_nomination | Reject a suggested commitment. |
Adjust what matters, and see why a memory ranks where it does.
mm_feedback | Raise, lower, pin or retire a memory based on human feedback. |
feedback_mark | Mark a memory as important or not important. |
feedback_promote | Promote a memory toward long-term retention. |
feedback_decay | Decay a memory that is stale but not wrong. |
feedback_correct | Correct a memory through a status change. |
mm_provenance | Trace a memory's full significance history. |
mm_rejections | Review what was demoted or rejected, newest first. |
How memories connect, and where agents see the same thing differently.
mm_explore_relationships | Show everything linked to one memory. |
mm_traverse_relationships | Walk the relationship graph outward from a memory. |
mm_explain_path | Find the shortest path between two memories. |
mm_divergences | List places where agents' perspectives disagree. |
mm_detect_divergences | Run a divergence-detection pass. |
mm_divergence_dismiss | Dismiss a divergence as a false positive. |
Procedural knowledge an agent keeps, and the rules it operates under.
mm_skill_put | Store a skill (a SKILL.md). |
mm_skill_get | Fetch a stored skill. |
mm_skill_list | List stored skills with version and digest. |
mm_capability_verify | Check for a stored procedure before an agent says "I can't". |
mm_policy_status | Show the agent's operating policies and whether they reached its prompt. |
mm_grant_residency | Ask for a memory to stay resident in the compiled context. |
mm_revoke_residency | Withdraw that request. |
For the platform team: pipeline state, latency, quotas and configuration.
mm_status | Health and configuration at a glance. |
mm_health | Pipeline health for an agent. |
mm_slo | Ingest-to-search latency over a rolling window. |
mm_queue_status | Where one memory is in the async pipeline. |
mm_stare_readiness | How mature each STARE dimension is. |
mm_episode_summary | Per-episode statistics. |
mm_compile_memory | Preview the agent's compiled memory file (Postgres). |
mm_lock_status | Diagnose the store's write lock. |
mm_get_quota | Quota state for the calling agent. |
mm_get_stare_policy | The effective STARE policy for an agent. |
mm_set_stare_policy | Set or preview a STARE policy override (admin). |
mm_explain_visibility | Explain why an agent can or cannot see a memory. |
mm_validate_auth_config | Validate the active scope-auth configuration (admin). |
Reading governance state works today. The write tools are defined so you can integrate against them now; until enforcement ships, each returns not_implemented_phase_b and changes nothing.
mm_get_governance | Read the retention, legal-hold and PII state of a memory. Works today. |
mm_forget | Forget a memory. |
mm_set_retention | Set a retention policy on a memory. |
mm_set_legal_hold | Place a memory on legal hold. |
mm_erase | Erase a memory. |
mm_erase_subject | Erase everything about one data subject. |
mm_redact | Redact PII from a memory by pattern. |
mm_tag_pii | Tag PII categories on a memory. |
mm_audit | Query the audit trail. |
The meaning-memory command handles setup, consolidation, health checks, and moving your
memory in and out. Export writes plain JSONL, so your data is readable without us.
$ meaning-memory version
meaning-memory 3.20.0
# Drain queued writes into the store (the scheduled job runs this nightly)
$ meaning-memory consolidate --agent-id support-bot --drain-only \
--workspace /srv/support-bot-mm --config-dir /srv/support-bot-mm
consolidation: agent=support-bot facts_added=0 watermark=n/a dry_run=False drain_only=True promote_only=False
# Export everything to plain JSONL you can read with jq
$ meaning-memory export --backend file --workspace /srv/support-bot-mm \
--agent support-bot --output ./export
entries: 1
sig_events: 1
relationships: 0
embeddings: 0
$ ls ./export
entries.jsonl manifest.json relationships.jsonl sig_events.jsonl
# Import it into another deployment
$ meaning-memory import --target file --input ./export \
--workspace /srv/restored-mm --agent support-bot
entries imported: 1
entries skipped (duplicate): 0Any runtime that can make an HTTP request can use Meaning Memory. Every request needs a bearer token, and a full OpenAPI spec ships with the customer kit.
Shell$ meaning-memory serve --ledger /srv/support-bot-mm/memory-ledger.md \
--events /srv/support-bot-mm/sig-events.jsonl \
--host 127.0.0.1 --port 8890 --token-env MM_REST_TOKEN
$ curl -s -X POST http://127.0.0.1:8890/v1/memories \
-H "Authorization: Bearer $MM_REST_TOKEN" -H "Content-Type: application/json" \
-d '{"text": "Acme renewal is November 14, 2026.", "category": "fact",
"source_agent": "support-bot"}'
{"mem_id":"666a4fca216bf30e","text":"Acme renewal is November 14, 2026.","category":"fact",
"sig":0.5,"status":"active","memory_type":"semantic", …}
$ curl -s "http://127.0.0.1:8890/v1/memories?q=renewal&limit=5" \
-H "Authorization: Bearer $MM_REST_TOKEN"
{"count":1,"entries":[{"mem_id":"666a4fca216bf30e","text":"Acme renewal is November 14, 2026.", …}]}
# No token, no access
$ curl -s -o /dev/null -w "%{http_code}" "http://127.0.0.1:8890/v1/memories?q=renewal"
401A license includes the engine wheel, the customer kit with the full install guide and OpenAPI spec, and reference deployments for Postgres and the file backend.
Request a License