Local mode — memory in a folder

What it is

The folder is the memory. mengram local reads and writes a memfmt tree:

memory/
  MEMORY.md                      index
  entities/Railway.md            what is true
  episodes/2026-07-30-deploy failed on a cold pool.md    what happened, and how it turned out
  procedures/Deploy to Railway.md                        how to do it, and whether it works
  .mengram/config.json           which model to use
  .mengram/quarantine.json       revisions the regression gate refused

Git diffs it. Obsidian draws it. memfmt validate checks it. Nothing expires, nothing asks for a key. Bring your own model. Extraction (turning a conversation into facts, events and workflows) and a failure revision need an LLM: an Anthropic or OpenAI key you already have, or Ollama (8B+, 8K+ context). Everything else — search, recall, the policy gate, recording outcomes — runs with no model and no network.

Install

pip install mengram-ai
mengram local init ./memory --provider anthropic --api-key sk-ant-...   # or --provider openai / ollama
export MENGRAM_MEMORY_DIR=$PWD/memory

init writes the folder and .mengram/config.json. With no --provider, an ANTHROPIC_API_KEY or OPENAI_API_KEY in the environment is used; with neither, the folder still works for everything but add.

Use it

mengram local add "I deploy to Railway from main; last time /health was probed before the pool was up"
mengram local search "railway pool"
mengram local procedures
mengram local feedback "Deploy to Railway" --success
mengram local feedback "Deploy to Railway" --failure --step 3 --context "connection refused on /health"
mengram local stat
mengram local quarantine

A failure with --context asks your model what belief broke and produces the next version of the workflow — unless the fix would silently break another workflow in the folder, in which case it is quarantined for you to review instead of shipped to the agent.

Start from your Claude Code history

An empty folder takes days to fill through the hooks. Your Claude Code sessions are already on disk, so seed it from them:

mengram import claude-code --memory ./memory            # 20 most recent sessions
mengram import claude-code --memory ./memory --last 50 --project shop

Each session becomes one extraction with the folder’s model, redacted for keys and tokens before it is read; nothing leaves your machine except those model calls. The import ends with what the folder now holds and the workflows it learned, with their record, and writes the map below. Imported sessions are listed in .mengram/claude-code-imported.json, so re-runs pick up only new ones (--reimport forces).

See what it holds

mengram local map --memory ./memory --open

One self-contained HTML page (memory-map.html in the folder, or --out), rendered from the same Markdown files, with nothing fetched or sent. Three views, in the order you would ask: who you are (entities by type, with facts and relations), what happened (episodes on a timeline, with outcomes), what your agent learned (each workflow as a step chain with the per-step record, its versions with the belief that broke, and the quarantine of revisions the regression gate refused). Re-run it after an import or a feedback.

Claude Code, all local

mengram hook install --memory ./memory

Installs the four hooks with the folder written into each command (hooks run without your shell profile, so an env var is not enough):

Hook	What it does locally
`SessionStart`	loads a profile of the folder — who you are, the workflows with a record
`UserPromptSubmit`	recalls facts, events and workflows that share words with your prompt
`Stop`	extracts the turn into the folder with your model (silent if none is configured)
`PreToolUse` on `Bash`	the policy gate: a workflow-shaped command that matches an `untested` or below-the-bar workflow is turned into a confirmation prompt

MCP for any client

mengram server --memory ./memory

Five tools over stdio: remember, recall, context_for, list_procedures, procedure_feedback — the same surface as the Claude connector, plus feedback so an agent can record an outcome from inside its tool call. Claude Desktop, Cursor, Windsurf and any MCP client can point at it:

{
  "mcpServers": {
    "mengram": {
      "command": "mengram",
      "args": ["server", "--memory", "/absolute/path/to/memory"]
    }
  }
}

What a procedure file looks like

---
memfmt_type: procedure
version: 2
success_count: 0
fail_count: 0
last_failure: the connection pool was warm when /health was probed
last_failed: 2026-09-04
entities:
  - Railway
---

# Deploy to Railway (v2 · 81% expected)

**When** — a change lands on main

**Preconditions**

- verify the pool is warm before probing /health

**Last failure** — 2026-09-04: the connection pool was warm when /health was probed

## Steps

1. push to main — the webhook does the rest (4✓/0✗)
2. watch the boot log (4✓/0✗)
3. wait for the pool — pool_max reached
4. verify /health — expect 200 within 60s (3✓/1✗)

## Evolution

- v1 → v2 (2026-09-04, 3✓/1✗): wait for the pool before probing

81% expected is not a ratio: v2 has no runs of its own yet, and the number is inherited from v1’s record, discounted. Once v2 runs it reads N% reliable. The steps that the revision left alone keep their counts; the new step starts untracked. See memfmt for the rules.

Where a folder stops being enough

Search is word overlap: past a few hundred files you want embeddings. Syncing a folder between machines is a git pull only until two machines disagree. Extraction runs only when you call it, not from every session in the background. That is what the cloud adds — and it writes this same format, so mengram export markdown hands you the folder back at any time.

Not yet

Multiple users per folder, the reflection and curator agents, and deleting a file that a rename left behind. Staleness is in as of 2.36.0: last_succeeded is written only by a recorded success, mengram local procedures shows it with days ago, and the map flags a workflow unverified for 30+ days. The cloud still lacks the column.

Getting Started

Concepts

SDKs

Integrations

Reference

Local mode — memory in a folder

What it is

Install

Use it

Start from your Claude Code history

See what it holds

Claude Code, all local

MCP for any client

What a procedure file looks like

Where a folder stops being enough

Not yet

​What it is

​Install

​Use it

​Start from your Claude Code history

​See what it holds

​Claude Code, all local

​MCP for any client

​What a procedure file looks like

​Where a folder stops being enough

​Not yet

What it is

Install

Use it

Start from your Claude Code history

See what it holds

Claude Code, all local

MCP for any client

What a procedure file looks like

Where a folder stops being enough

Not yet