Quickstart

This page takes you from a fresh install to an agent that stores a promise in one session and finds it again in the next. It uses the file backend, which needs no database and keeps everything in one directory. When you are ready for several agents on shared storage, see Scoping and sharing memory.

You need Python 3.11 or later and the Meaning Memory wheel from your customer kit.

1. Install the engine with the MCP server

pip install "meaning_memory-<version>-py3-none-any.whl[mcp]"

The mcp extra installs mm-mcp, the server your agent connects to. Check the install:

$ meaning-memory version
meaning-memory 3.20.0

2. Create an agent workspace

meaning-memory init writes everything one agent needs into a single directory: the base and per-agent configuration, a consolidation script, a schedule entry and a README.

meaning-memory init --agent-id support-bot --backend file \
    --workspace /srv/support-bot-mm --non-interactive

✓ Workspace created at /srv/support-bot-mm/
  ✓ mm-base.toml
  ✓ agents/support-bot.toml
  ✓ scripts/mm_consolidate_bridge.py
  ✓ scripts/mm_handlers.py
  ✓ scripts/prompts/consolidation.md
  ✓ README.md
  ✓ data/pii-denylist.txt
  ✓ cron.d/support-bot-consolidate
✓ Generated Python compiles cleanly
✓ Config validates cleanly (mm-config validate clean)

Agent ids are lowercase letters, digits, hyphens and underscores, starting with a letter.

Extracting facts with a model

init also writes scripts/mm_handlers.py, where consolidation calls a model to extract new facts from what the agent saw. Out of the box it uses a stub that extracts nothing. --provider openai, --provider anthropic or --provider ollama generates a handler for that model; wiring it into the consolidation pipeline is covered in the consolidation guide in your customer kit. Everything on this page works without it.

3. Check the environment

meaning-memory doctor --profile quickstart --agent support-bot \
    --workspace /srv/support-bot-mm --config-dir /srv/support-bot-mm

On a new install the summary reads:

15 OK, 1 warning
Overall: warning

The one warning is cron-runs-log, which looks for a log of scheduled jobs that a new install does not have. It is safe to ignore here. Any other warning or failure includes a remediation hint.

4. Write an access policy

Every agent runs under an access policy that lists the memory scopes it may read and write. For one agent on the file backend, the policy is short:

/srv/scope_auth.yaml

version: 1
agents:
  support-bot:
    allowed_scope_groups: [agent:support-bot]
groups:
  agent:support-bot: { backfill_policy: forward_only }

The MCP server will not start without a policy. For local experiments only, MM_ALLOW_UNSCOPED_DEV=true skips this step.

5. Connect your agent

Add mm-mcp to your agent’s MCP configuration. For Claude Code, that is a .mcp.json file in your project:

{
  "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"
      }
    }
  }
}

MM_AGENT is the agent the server runs as. MM_ACTOR is the name recorded on each write. MM_ALLOW_INTERNAL=1 enables the tools that write memory; leave it out for a read-only connection. Other runtimes are covered under Connect your agent.

6. Keep a promise across sessions

In one session, the agent stores a commitment with a due date:

mm_remember({
  "source": "agent",
  "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`; …

In a later session, with no chat history, the agent asks what it owes:

mm_due_commitments({})

## Commitments (due / overdue)

📅 Scheduled
- Send Dana at Acme the updated pricing sheet. — due 2026-11-07 · c9f737d32b583106

Commitments are stored straight away and never fade from this list because of age. They stay until the agent closes them. See Commitments for due dates, recurring duties and closing.

7. Schedule consolidation

Other memories, such as facts and observations, are queued when the agent writes them. The writing agent can search its own queued memories straight away. Consolidation moves them into the store and rebuilds the agent’s compiled memory file, MEMORY.md. See When memories become searchable.

Run it once by hand:

MM_BACKEND=file meaning-memory consolidate --agent-id support-bot --drain-only \
    --workspace /srv/support-bot-mm --config-dir /srv/support-bot-mm

Then put the same command on a schedule, for example nightly in cron:

5 0 * * *  mm  MM_BACKEND=file meaning-memory consolidate --agent-id support-bot --drain-only --workspace /srv/support-bot-mm --config-dir /srv/support-bot-mm

Caution

In this release, the cron.d/support-bot-consolidate file and scripts/mm_consolidate_bridge.py that init creates only check the configuration; they do not move queued memories. Schedule the command above instead.

Next steps

• Connect your agent in Claude Code, Cursor, Hermes, LangGraph or over REST.
• Commitments: due dates, recurring duties and closing.
• Export and import: move your memory to another deployment, or out entirely.
• MCP tools: every tool and its arguments.