What's New in v0.4.0

IronMem is now a full durable memory stack: reversible originals, typed memories, temporal graph recall, source-backed retrieval, adaptive skim/expand context, sleep-cycle compression, and 21 MCP tools.

  • CCR — losslessly reversible memory (Headroom pattern) — every truncated tool output and the verbatim pre-LLM session transcript is preserved in a content-addressed, deduplicated, byte-exact compressed blob store inside the DB. retrieve_original pulls the exact original back by observation_id, memory_id, raw blob hash, or the chunk_id expansion handle.
  • Memory scoping & typed memories (Supermemory patterns) — memories carry a scope (project vs. user/cross-project) and a kind (session, fact, error_solution, preference, procedural, architecture, learned_pattern, project_config, profile). Session-start injection ranks project ∪ user memories and boosts durable kinds.
  • Local-first session graduation — deterministic local compression is the default and requires no cloud credential. Optional cloud enrichment can add a narrative plus typed facts, but provider failure always falls back to the local archive instead of stranding observations.
  • Record-run retrieval stack — hybrid FTS/vector/graph recall now includes routed weighted fusion, source-fact retention, temporal event boosts, multi-hop query expansion, deterministic query decomposition, entity alias expansion, temporal conflict handling, structured-evidence reranking, rerank re-anchoring, and optional cross-encoder reranking.
  • Adaptive working-memory skim — every compressed or explicit memory gets durable memory_chunks with density, kind, title, token estimate, and optional exact transcript offsets. Agents can skim broadly with memory_skim, then expand exact evidence with retrieve_original(chunk_id=...).
  • Governed recall — memories carry namespace, source type, trust tier, writer/source provenance, classification, consent state, residency, retention metadata, legal hold, tombstone state, record hash, and an append-only ledger hash chain. Reads are namespace-scoped and active-only by default; PHI/PII writes fail closed unless consent is granted.
  • Closed-loop memory quality — injection events and explicit feedback reinforce useful memories and decay repeatedly ignored or corrected memories without deleting provenance.
  • Sleep-cycle auto-compression — ironmem sweep and ironmem scheduler run compact idle or high-volume sessions without manual session_end, with DB leases, dry-run mode, audit events, and slower dream/reflection passes.
  • GPU-ready cross-encoder reranking — rerank.backend = "cross_encoder" uses the local ONNX reranker when available, with a gpu feature for CUDA-backed benchmark-scale runs and a safe fallback when the model is unavailable.
  • AST-bound Rust anchors — ironmem code-relink uses Tree-sitter to hash Rust symbols and relink memories when code moves across files.
  • Reflection, snapshots, and sync — dry-run-first consolidation proposals, CCR-backed project brain snapshots, and an idempotent Lamport-clock sync event log support long-lived and multi-agent memory workflows.
  • remember tool — store an explicit, typed memory in one call (scope, kind, text, tags). User-scope facts follow you into every project and also enter the skim layer.
  • User profile — cross-project memories are distilled into a single always-injected profile. Read/regenerate with get_profile / refresh_profile.
  • Correction miner — error→fix loops are mined into error_solution memories and surfaced via list_corrections, so past fixes resurface when work recurs.
  • 21 MCP tools now — including memory_skim, retrieve_original, remember, get_profile, refresh_profile, list_corrections, memory_graph, and reconcile_memory_graph.
  • Temporal recall + graph recall — dated facts and event_time metadata power timestamp lookup, while memory_edges stores structured source | relation | target edges with valid-time filters and provenance. Temporal questions route toward date-bearing facts; relationship questions route toward graph edges.
  • Memory Graph Workbench — the built-in local UI is now a temporal graph investigation surface with project/query/date/history filters, an interactive canvas, retrieval-trace highlighting, governed memory metadata, structured chunks, graph provenance, and one-click expansion to exact original source.
  • Benchmarked on LoCoMo: 68.4% overall (Gemini 2.5 Pro answerer + Pro judge, 1,540 scored questions, 0 errors) with governance-off retrieval, +2.1 points over the governed baseline. Full harness, result files, and reproduction: ironmem-locomo-benchmark. See Benchmarks.
  • External storage adapters: a StorageBackend trait with a HYBRID mode lets vector and graph layers run on real external backends (Qdrant over HTTP for vectors, Neo4j for the graph) instead of only the embedded SQLite store, while keeping the native path the default.
  • Retrieval + governance instrumentation: governance-cost timings in /status, a temporal-trust trajectory signal, a compression coverage pass, and the path-to-70 retrieval batch (routed fusion, structured evidence, pool/context tuning, multi-hop decomposition, entity aliases, temporal conflict handling, and source-backed evidence chains).
  • Valid-time temporal recall: remember accepts an optional event_at (an ISO YYYY-MM-DD date or a YYYY-MM-DD..YYYY-MM-DD range) for when an event actually occurred, distinct from the storage time (created_at). Valid-time dates are surfaced through an event_times side map on search, list, context, and skim results, powering time-aware retrieval.
  • Derived (inferred) memories: reflection can derive new memories from existing ones, governed as source_type=derived / kind=inference with a derives provenance edge and a ledger entry per inference. Derived memories are quarantined from default retrieval until a caller explicitly asks for them, so inferences never silently pollute primary recall.
  • Opt-in auto-dream trigger: a thin background watcher (auto_dream.enabled, default off, with a gap_minutes idle threshold) fires a consolidation and synthesis pass on projects that have gone idle. Every auto-triggered pass is recorded in the governance ledger with a trigger_reason, so it stays auditable instead of a black box.
  • Current verification: cargo test --bin ironmem passes 228 tests with 1 ignored benchmark, MCP stdio cleanliness passes, and the strict local-onnx clippy gate is clean.
  • Still zero telemetry. Still local-first. Your data stays yours.
  • Multi-provider compression — use OpenAI, Google Gemini, or Anthropic as your LLM. Set "provider": "openai" in settings.
  • Neovim plugin — native Lua plugin with auto session lifecycle, :IronMemSearch, :IronMemStatus
  • Windows support — install.ps1, platform-aware messages, robust home directory detection
  • Web UI — browse, search, and delete memories at http://localhost:37778/ui
  • Discovery tools — list known projects, search across all projects, and inspect per-project session history
  • Still zero telemetry. Still local-first. Your data stays yours.
  • Initial 13 MCP tools — session_start, session_end, record_event, compress_session, get_context, get_status, list_memories, search_memories, search_global, list_projects, list_sessions, inject_context, wipe_project
  • Dual database — SQLite (local, FTS5 full-text search) + Postgres (self-hosted, tsvector) via DATABASE_URL
  • Every MCP client — Claude Desktop, Claude Code, Cursor, Windsurf, ChatGPT Desktop, Zed, and more
  • Docker deployment — docker-compose up for remote/team setups with Postgres
  • ironmem mcp — new subcommand for direct MCP stdio transport (Claude Desktop/Code)
  • REST server still works — existing hooks and curl-based workflows unaffected

IronMem gives AI coding tools persistent memory across sessions. It silently records what happened during your session, compresses it into concise memory, and injects that context into your next session automatically.

No copy-pasting. No rebuilding context from scratch. No "remember when we refactored auth yesterday?"

Works with every major AI coding tool — Claude Code, Claude Desktop, Cursor, Windsurf, ChatGPT Desktop, GitHub Copilot, Zed, VS Code, and any MCP-compatible client.

Compress with the LLM you already pay for — Anthropic Claude, OpenAI GPT-4o, Google Gemini, or Vertex AI Gemini. Switch providers with one config change.

Free and open source. Runs locally or on your own infrastructure. No telemetry. No cloud dependency. No subscription. SQLite or Postgres storage. Single Rust binary.

Why this exists

AI coding tools are great inside a session and terrible across sessions. They help you ship faster, but every fresh session forgets your architecture decisions, debugging trail, and what changed yesterday.

IronMem fixes the handoff.

Before vs after

Without IronMem:

"We already changed the auth middleware, switched to JWT, updated the migration, and fixed the failing tests in billing. Let me explain the whole thing again."

With IronMem:

Open a new session. Your assistant already has the recent project context.

Quick Start

  1. Install IronMem: 
    curl -fsSL https://raw.githubusercontent.com/BMC-INC/Iron-mem/main/install.sh | bash
  2. Add your API key to IronMem's key file: 
    echo "your-key-here" > ~/.ironmem/api_key && chmod 600 ~/.ironmem/api_key

    Prefer the key file over export ANTHROPIC_API_KEY. Claude Code and some other tools bill against ANTHROPIC_API_KEY whenever it is set in your shell. The key file keeps IronMem's key out of your environment so it cannot change how other tools bill. IronMem still honors the env var if you prefer it.

  3. Start coding! IronMem handles the rest silently in the background.

Table of Contents

The Problem

Every time you start a new session with Claude Code, Cursor, Copilot, or any AI coding assistant, it starts from zero. It does not know what you built yesterday, what broke, or what you decided.

You end up re-explaining context every single session.

The Fix

IronMem silently records what happens during your coding session, compresses it with your configured provider, and injects that context into your next session automatically.

No setup per session. No copy-pasting. No "remember when we..."

Without IronMem: "Hey Claude, remember yesterday we refactored the auth middleware and switched to JWT? And the database migration for the users table? And..."

With IronMem: You open a new session. It already knows.

Who Should Use This?

IronMem is designed for:

  • Developers frustrated with re-explaining context to AI tools every single session.
  • Teams working on large, multi-session projects where context gets easily lost.
  • Developers frequently switching between multiple AI tools like Copilot, Claude Code, Windsurf, or Cursor.
  • Solo developers who want to maintain flow and continuity without manual effort.

How It Works

flowchart LR
    A["🟢 Session Start"] -->|inject memories| B["📄 IRONMEM.md"]
    B --> C["🤖 AI reads context"]
    C --> D["🔧 You code"]
    D -->|every tool call| E["🗄️ SQLite"]
    D --> F["🔴 Session End"]
    F -->|compress via LLM| G["🧠 Memory"]
    G -->|next session| A

    style A fill:#22c55e,color:#fff,stroke:none
    style F fill:#ef4444,color:#fff,stroke:none
    style G fill:#8b5cf6,color:#fff,stroke:none
    style E fill:#0ea5e9,color:#fff,stroke:none

Everything runs locally. Your data stays on your machine.

Current Memory Stack

IronMem now stores memory in several cooperating layers rather than one flat summary:

  • Session transcript CCR: verbatim pre-LLM transcripts and large/truncated tool outputs in content-addressed compressed blobs.
  • Narrative memories: concise session summaries in the memories FTS table.
  • Typed facts: separate kind=fact memories extracted from compression, so dates, names, quantities, and direct answers survive summarization.
  • Procedural memories: reusable workflow rules as kind=procedural.
  • Error solutions: mined fail→edit→pass loops as kind=error_solution.
  • User profile: global scope=user, kind=profile memory injected across projects.
  • Temporal graph: source | relation | target edges with valid-time fields, confidence, and memory provenance.
  • Adaptive skim chunks: memory_chunks rows with chunk_id, density, kind, title, token estimate, and optional exact transcript byte offsets.
  • Observation logs (opt-in): the Observer pass emits an append-only, timestamped, priority-tagged log beside the narrative — each line its own governed kind=observation memory with the event's own date and lineage back to its session — so specifics survive that summarization would generalize away.
  • Maturity tiers: memories graduate draft → stable → core via the dream sweep as they earn injections and positive feedback, feeding the optional activation ranking lever.

Retrieval is routed by query shape:

  • Temporal lookup queries prioritize date-bearing kind=fact memories and suppress graph-only hits that would otherwise promote relationship memories over timestamp answers.
  • Relationship queries keep graph fusion enabled and rank edges by relation/source/target overlap.
  • General project recall blends FTS, vectors when available, event-time boosts, graph signals, kind boosts, importance, and recency.
  • Skim/expand workflows use memory_skim or /skim first, then retrieve_original with a chunk_id for exact transcript evidence.

This is intentionally model-agnostic. The durable store is hard-token, structured, and auditable, so Claude, Codex, Operator OS, desktop clients, and remote MCP clients can share the same backing memory.

Benchmarks

IronMem is evaluated on LoCoMo (Maharana et al., ACL 2024), a long-term conversational memory benchmark. The full harness, result files, and reproduction steps live in a dedicated repo: ironmem-locomo-benchmark.

Headline (Gemini 2.5 Pro answerer + Pro judge, hybrid retrieval, pool 100, retrieve-limit 25, v2 answer prompt, 1,986 questions of which 1,540 are scored, 0 errors):

Configuration Overall single_hop multi_hop temporal open_domain
Governed (trust-tier ranking on) 66.3% 69.0% 50.0% 77.9% 52.1%
Governance-off (pure relevance ranking) 68.4% 72.1% 52.5% 78.2% 50.0%

Setting the writer-tier and temporal-trust retrieval weights to 0 (ranking on pure relevance) scores 68.4%, +2.1 points over the governed configuration. Governance metadata (writer identity, trust tier, provenance, ledger) is still recorded and queryable on every memory; the finding is only that letting trust tier tilt retrieval ranking was net-negative on this benchmark. The benchmark repo has the per-category analysis, second-judge agreement (Cohen's kappa 0.88), and the documented path past 70%.

LongMemEval

An in-repo harness runs LongMemEval (Wu et al., ICLR 2025) against the live write + retrieval pipeline with per-ability breakdowns (information extraction, multi-session reasoning, temporal reasoning, knowledge updates, abstention):

ironmem bench longmemeval --data longmemeval_s.json               # scored run (needs an LLM API key)
ironmem bench longmemeval --data longmemeval_s.json --full-context # the published baseline column
ironmem bench longmemeval --data longmemeval_s.json --dry-run      # pipeline smoke test, no API key
ironmem bench longmemeval --data longmemeval_s.json \
  --stratified-per-ability 2 --min-accuracy 0.50                    # representative paid gate

Every report records the answer model, judge model, embedder, and retrieval depth so runs are comparable — scores are only published next to a same-model full-context baseline. Deterministic retrieval-quality regression checks (42 cases across multi-hop, temporal, open-domain, knowledge-update, abstention, governance-parity, entity, and chunk clusters) run via ironmem eval and gate CI on every change.

LongMemEval writes each completed question to an atomic checkpoint inside the --out directory before advancing. Restart the same command with the same dataset, commit, models, embedder, and options to resume without repeating paid answer or judge calls. A mismatched configuration is rejected; use a new --out directory for a fresh run.

The harness indexes one lossless memory per timestamped session and presents retrieved sessions chronologically, matching LongMemEval's official session-granularity generation contract. This keeps complete dialogue rounds together and prevents the retrieval budget from being consumed by isolated turns from the same session. The answer prompt extracts relevant information before reasoning, and the judge uses LongMemEval's ability-specific rubrics. Raw judge verdicts are stored with every checkpoint; anything other than exactly yes or no is a visible harness error rather than a silent incorrect score.

For long scored runs, scripts/run_longmemeval.sh wraps the harness in a durable launcher: preflight (dataset SHA-256, clean tree, disk, battery, ADC), a release local-onnx build, a no-credit stratified dry canary (canary), and a 12-question paid stratified gate (scored-canary --authorized). A full run (full --authorized) is refused unless that exact release binary has passed the scored gate. Paid jobs are one-shot macOS launchd services (KeepAlive=false) wrapped by caffeinate, with a durable console log, recorded PID/label, atomic exit.status, and a unique checkpointed --out.

Install

curl -fsSL https://raw.githubusercontent.com/BMC-INC/Iron-mem/main/install.sh | bash

Or clone and build manually:

git clone https://github.com/BMC-INC/Iron-mem.git
cd Iron-mem
chmod +x install.sh
./install.sh

Windows:

git clone https://github.com/BMC-INC/Iron-mem.git
cd Iron-mem
powershell -ExecutionPolicy Bypass -File install.ps1

Add IronMem to your PATH and write your API key to IronMem's key file:

export PATH="$HOME/.ironmem/bin:$PATH"          # in ~/.zshrc / ~/.bashrc
echo "your-key-here" > ~/.ironmem/api_key && chmod 600 ~/.ironmem/api_key

Use the key file, not export ANTHROPIC_API_KEY. A global ANTHROPIC_API_KEY can change how other tools bill. IronMem reads ~/.ironmem/api_key automatically.

Restart your terminal and Claude Code. That's it.

Requirements: Rust/Cargo (the installer will tell you if it's missing)

CLI

ironmem server              # Start REST + MCP SSE server
ironmem mcp                 # Start MCP stdio server (for Claude Desktop/Code)
ironmem serve               # Start SSE server with bearer token auth
ironmem serve --public      # Same + Cloudflare Tunnel for remote MCP clients
ironmem serve --public --no-auth  # Authless public tunnel for claude.ai personal use
ironmem status              # Health check + DB stats
ironmem projects            # All projects with stored memories
ironmem list                # Recent memories for current project
ironmem search "auth middleware"  # Hybrid (keyword + semantic) search across memories
ironmem search-global "auth middleware"  # Search across all projects
ironmem sessions            # Session history for current project
ironmem inject              # Manually rebuild IRONMEM.md (relevance-ranked)
ironmem remember "..."      # Store an explicit memory (--scope user, --kind preference, --tags)
ironmem remember "..." --classification pii --consent-state granted --namespace tenant-a
ironmem forget <memory-id> --reason "user requested erasure"
ironmem profile             # Show the user profile (--refresh to regenerate it)
ironmem corrections         # List mined error→fix memories (--all for every project)
ironmem graph "Operator OS" # Query temporal graph edges (--history includes superseded edges, --at filters valid time)
ironmem graph-delete <edge-id> # Mark a bad graph edge user_deleted
ironmem graph-update <edge-id> --source A --relation owns --target B # Human-curate a graph edge
ironmem reconcile --dry-run # Preview duplicate/current-state graph reconciliation
ironmem graph-backfill --limit 50 # Extract graph relations from older memories
ironmem feedback <memory-id> --signal used --weight 1 # Reinforce or decay a memory
ironmem reflect --dry-run # Propose durable-memory consolidation
ironmem code-relink --dry-run # Tree-sitter Rust AST anchoring/relinking
ironmem snapshot create --label before-refactor # CCR-backed project brain snapshot
ironmem sync publish --node ci --op error_solution --payload '{"memory_id":1}' # Multi-agent event log
ironmem eval                # Run deterministic memory-quality evals into docs/evals
ironmem bench longmemeval --data longmemeval_s.json # LongMemEval harness (--full-context baseline, --dry-run keyless smoke)
ironmem compliance-report   # EU AI Act Art. 12/13 report: ledger chain verification, governance inventory, snapshots
ironmem ledger-migrate      # Export deterministic fork evidence; add --apply to begin a repaired forward-only epoch
ironmem lineage <memory-id> # Memory→action lineage: writer, ledger trail, every injection into an agent context
ironmem compress <id>       # Manually compress a session
ironmem sweep --compress-idle 30m --min-observations 50 --dry-run # Preview auto-compression
ironmem sweep --dream-due --apply # Run due sleep/dream consolidation
ironmem scheduler run       # Long-lived unattended sleep-cycle worker
ironmem scheduler install-launchd # Install/start the macOS sleep-cycle agent
ironmem embed               # Backfill semantic embeddings for existing memories
ironmem gc                  # Reclaim unreferenced CCR blobs (after wipes)
ironmem wipe                # Delete all memories for current project
ironmem config              # Print current settings

Multi-Provider Support

IronMem works as an MCP server (native integration) or via IRONMEM.md (plain markdown, universal):

Platform MCP Native IRONMEM.md Setup
Claude Code Yes Yes Setup →
Claude Desktop Yes Yes Setup →
claude.ai Yes Yes Setup →
Cursor Yes Yes Setup →
Windsurf Yes Yes Setup →
ChatGPT Desktop Yes — Setup →
Zed Yes — Setup →
VS Code (Copilot/Continue/Cline) Yes Yes Setup →
Any MCP Client Yes — stdio or SSE transport
Any AI Tool — Yes Read IRONMEM.md as project context

MCP Setup

IronMem supports two MCP transports:

  • stdio — for local clients that launch the server themselves (Claude Code, Claude Desktop, Cursor)
  • Streamable HTTP — for remote/cloud clients that connect over HTTP. Uses request/response and bearer-token auth, so it works through tunnels and reverse proxies for clients that support static bearer tokens.

Once connected over MCP, clients can record sessions, retrieve memories, inspect graph state, scan adaptive skims, and expand exact originals directly.

Claude Code MCP Setup

Claude Code connects via stdio — it launches ironmem mcp directly.

Option A: CLI (recommended)

claude mcp add ironmem -- ~/.ironmem/bin/ironmem mcp

Option B: Project .mcp.json (share with your team)

Create .mcp.json in your project root:

{
  "mcpServers": {
    "ironmem": {
      "command": "~/.ironmem/bin/ironmem",
      "args": ["mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

Note: Claude Code hooks and MCP can coexist. Hooks use the REST API for automatic observation recording; MCP gives you direct tool access.

Claude Desktop MCP Setup

Claude Desktop also connects via stdio.

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ironmem": {
      "command": "/Users/YOU/.ironmem/bin/ironmem",
      "args": ["mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

Replace /Users/YOU with your actual home directory path. Restart Claude Desktop after saving.

claude.ai (Web)

claude.ai runs in the cloud, so it cannot reach localhost.

IronMem is a local-first tool. The recommended setup for full MCP access is Claude Code or Claude Desktop using stdio.

Anthropic's current claude.ai custom connector UI supports authless and OAuth-based remote MCP servers, but not a manual static bearer-token field. For personal use, the honest compatibility path is an authless ephemeral tunnel:

ironmem serve --public --no-auth

That command does three things:

  1. Starts the SSE server with no auth
  2. Launches a Cloudflare Tunnel (free, no account needed) to expose it publicly
  3. Prints the public URL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  IronMem SSE Server
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Local:  http://127.0.0.1:37779/mcp
  Auth:   Disabled (--no-auth)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Public URL: https://xxx-yyy-zzz.trycloudflare.com
  Remote MCP setup:
    URL:   https://xxx-yyy-zzz.trycloudflare.com/mcp
    Auth:  None
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

In claude.ai:

  1. Open Settings
  2. Open Integrations
  3. Choose Add custom connector
  4. Set Name to IronMem
  5. Paste the printed https://...trycloudflare.com/mcp URL into Remote MCP server URL
  6. Leave the OAuth fields blank

The trycloudflare.com URL is ephemeral and changes whenever you restart the public tunnel, so update your connector URL each time you relaunch ironmem serve --public --no-auth.

This is no longer local-only. The tunnel exposes your MCP endpoint over the internet for as long as it is running.

For a personal local tool, this tradeoff is often acceptable because the URL is short-lived and changes on each restart. Still, use --no-auth deliberately.

Without --no-auth: ironmem serve and ironmem serve --public use bearer-token auth for clients that support static bearer tokens.

Requirements: Install cloudflared for best results. IronMem falls back to npx cloudflared if it is not installed.

Cursor / Windsurf MCP Setup

Both use stdio. Add to your MCP settings:

Cursor: Settings → MCP → Add Server

Windsurf: Settings → MCP → Add Server

{
  "ironmem": {
    "command": "~/.ironmem/bin/ironmem",
    "args": ["mcp"]
  }
}

Other MCP Clients

Any MCP client that supports stdio transport can use IronMem:

{
  "command": "~/.ironmem/bin/ironmem",
  "args": ["mcp"]
}

For clients that support Streamable HTTP, start the server and point the client at http://localhost:37779/mcp:

ironmem serve

MCP Tools

IronMem currently exposes 21 MCP tools:

Tool Purpose
session_start Start a new project session and return a session_id
record_event Record a tool call observation
session_end End a session and trigger compression
compress_session Manually compress a session
get_context Retrieve project memories; results include expansion chunks with chunk_id handles
memory_skim Return project or global compressed skim chunks for broad working-memory scan
retrieve_original Expand exact original text by chunk_id, observation_id, memory_id, or blob hash
get_status Return DB stats, CCR stats, graph edge count, and memory chunk count
list_memories List recent memories for a project
search_memories Hybrid search inside one project
search_global Hybrid search across every project
list_projects List known projects with stored memories
list_sessions List session history for a project
inject_context Write IRONMEM.md into a project root
remember Store an explicit typed/scoped memory
get_profile Return the current cross-project user profile
refresh_profile Regenerate the user profile
list_corrections List mined error_solution memories
memory_graph Query temporal graph edges for an entity, with optional valid-time filtering
reconcile_memory_graph Dry-run or apply duplicate/current-state graph reconciliation
wipe_project Delete all memories for one project

The intended agent loop is:

  1. Call get_context for focused recall or memory_skim for a broader scan.
  2. Inspect returned chunk_id values.
  3. Call retrieve_original with the chosen chunk_id when exact evidence is needed.

Neovim Plugin

IronMem includes a native Neovim plugin that communicates via MCP stdio.

Install with lazy.nvim:

{
  "BMC-INC/Iron-mem",
  config = function()
    require("ironmem").setup({
      -- binary = "~/.ironmem/bin/ironmem",  -- default
      -- auto_start = true,   -- session_start on VimEnter
      -- auto_end = true,     -- session_end on VimLeavePre
      -- record_events = true, -- record buffer writes
    })
  end,
}

Commands:

Command Description
:IronMemStart Manually start a session
:IronMemEnd End session and compress
:IronMemStatus Show database stats
:IronMemSearch <query> Search memories in a split buffer

Memory Graph Workbench

When the REST server is running, the built-in workbench is available at:

http://localhost:37778/ui

The Graph view explores a bounded temporal relationship window across one project or the full local store. Filter by entity/relation text, valid date, superseded history, and graph size; then select any node or relationship to inspect the backing memory, governance metadata, structured chunks, graph edges, and exact CCR source. Retrieval Trace runs the configured retrieval stack for a project and highlights the evidence chains it would return to an agent. Memories, Sessions, and Maintenance remain available as dedicated views.

REST API

The REST server runs on http://localhost:37778 by default. Current high-signal endpoints:

Endpoint Purpose
POST /session/start Start a session
POST /event Record an observation
POST /session/end End and compress a session
POST /compress Manually compress a session
GET /context?project=&query=&namespace=&limit=&rerank= Retrieve project memories plus expansion chunks in one governance namespace
GET /skim?project=&namespace=&limit= Return adaptive project skim chunks in one governance namespace
GET /skim?global=true&namespace=&limit= Return adaptive global skim chunks in one governance namespace
POST /retrieve_original Expand by chunk_id, observation_id, memory_id, or hash
POST /remember Store an explicit typed/scoped memory
GET /profile / POST /refresh_profile Read or regenerate the user profile
GET /corrections List mined error-solution memories
GET /graph?entity=&project=&history=&at=&limit= Query temporal graph edges
GET /api/graph/window?project=&query=&history=&at=&limit= Browse a bounded workbench graph window
GET /api/memories/{id}/evidence Inspect memory metadata, chunks, and graph provenance
GET /memory/{id}/lineage Memory→action lineage: writer, governance, ledger trail, every injection with session/rank/query
GET /compliance/report EU AI Act Art. 12/13 report: hash-chain verification per namespace, governance inventory, snapshots
POST /feedback Reinforce or decay a memory's ranking
GET /snapshots / POST /snapshots List or create CCR-backed brain snapshots
GET /status Health, DB stats, CCR stats, governance op timings, and retrieval tier metrics

With agent_keys configured (see Governed Memory), every REST request must present a listed bearer token; the resolved agent is confined to its namespace allowlist and writes are ledger-attributed agent:<id>.

Client SDKs

Thin zero-dependency typed clients over the REST API live in-repo:

  • Python (sdk/python): pip install ./sdk/python → from ironmem import IronMem
  • TypeScript (sdk/typescript): Node 18+/browsers/Deno/Bun via global fetch

Both cover session lifecycle, governed remember, ranked context, feedback, lineage, and compliance_report (typed responses), with bearer/agent-key auth.

Governed Memory

IronMem is still independent of SovereignClaw, but it now has its own governance envelope for durable recall. The default namespace is local, so existing single-user installs continue to work without new flags. Multi-tenant or control-plane callers can set namespace to isolate reads, search, skim, list, context injection, and explicit memory writes.

Governance fields accepted by CLI, REST /remember, and MCP remember include:

Field Purpose
namespace Tenant/realm boundary. Defaults to local.
source_type user_input, tool_output, agent_generated, derived, external, or sync_peer.
trust_tier high, medium, low, or untrusted.
writer_identity / source_ref Provenance for who/what wrote the memory.
parent_memory_id Lineage for derived facts and compression children.
classification public, internal, confidential, restricted, pii, or phi.
consent_state required, granted, denied, or withdrawn; pii and phi require granted.
residency, retention_policy_id, expires_at Policy metadata; expires_at is enforced by active recall filters.
legal_hold Prevents governed deletion while true.

Every governed write stores a canonical record hash and appends to memory_ledger, linking each entry to the previous namespace hash. Deletion uses ironmem forget or the existing project wipe paths, which now call governed deletion per memory: legal holds block deletion, active recall is tombstoned first, the ledger records the forget event, vectors are purged, and CCR blobs are garbage-collected when no references remain.

Example:

ironmem remember "Customer asked to retain audit exports for 7 years" \
  --namespace tenant-a \
  --classification confidential \
  --consent-state granted \
  --writer ops-agent \
  --residency us \
  --retention-policy-id audit-7y

ironmem search "audit exports" --namespace tenant-a
ironmem forget 42 --actor privacy-admin --reason "retention window expired"

Compliance product

The governance envelope is auditable end-to-end, mapped to the EU AI Act's record-keeping (Art. 12) and transparency (Art. 13) obligations — see [docs/compliance/eu-ai-act-mapping.md](https://github.com/BMC-INC/Iron-mem/blob/main/docs/compl