铁记忆

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 (in ~/.zshrc or ~/.bashrc) 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 makes Claude Code (and similar tools) bill against pay-as-you-go API credit instead of your subscription. 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)

---

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 standard 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, IronMem now supports project discovery directly:

• list_projects — show every project with stored memories
• search_global — search across all projects
• list_sessions — inspect session history inside a project

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 (installed by install.sh) and MCP can coexist. The hooks use the REST API for automatic observation recording; MCP gives you direct tool access. You can use both, or just one.

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.

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

Install Ollama, then pull an embedding model:

ollama pull nomic-embed-text

Docker Deployment

Run IronMem with Postgres for team/remote setups:

ANTHROPIC_API_KEY=your-key docker-compose up --build

This starts IronMem with Streamable HTTP on http://localhost:37779/mcp and Postgres 16, plus the REST server on http://localhost:37778.

---

Quick Start

1. Install IronMem:

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

   echo "your-key-here" > ~/.ironmem/api_key && chmod 600 ~/.ironmem/api_key
   

---

Configuration

~/.ironmem/settings.json:

{
  "port": 37778,
  "provider": "anthropic",
  "model": "claude-sonnet-4-6-20250627",
  "inject_limit": 5,
  "max_observation_bytes": 2048,
  "db_path": "/Users/you/.ironmem/mem.db",
  "database_url": null,
  "mcp_transport": "stdio",
  "mcp_sse_port": 37779,
  "auth_token": null,
  "embedding": {
    "provider": "auto",
    "model": null,
    "ollama_url": "http://localhost:11434",
    "weights": { "relevance": 0.5, "recency": 0.3, "importance": 0.2 },
    "recency_half_life_days": 30
  }
}

All fields optional. Sensible defaults provided. auth_token is generated automatically the first time you run ironmem serve without --no-auth. The embedding block is optional — omit it entirely and IronMem behaves exactly as before (keyword-only search, recency injection).

Environment Variables

API Key

IronMem needs an LLM API key to compress session observations into memories.

Recommended (Anthropic): write the key to ~/.ironmem/api_key (echo "your-key" > ~/.ironmem/api_key && chmod 600 ~/.ironmem/api_key). Keeping it in this file rather than a global ANTHROPIC_API_KEY export avoids changing how other tools bill — Claude Code, for instance, charges pay-as-you-go API credit whenever ANTHROPIC_API_KEY is set in the environment, instead of using your subscription. IronMem reads the file automatically (it also works when the background server is spawned via nohup, where some shells strip env vars from child processes).

IronMem still honors the per-provider environment variable if you prefer it — ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY. The file fallback applies to the default Anthropic provider.

---

Check if the API key is accessible (the key file is the recommended source)

cat ~/.ironmem/api_key # Should contain your key echo $ANTHROPIC_API_KEY # Optional env-var fallback (may be empty)

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:

---

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.

---

Troubleshooting

Server not starting:

ironmem status                           # Check if server responds
cat ~/.ironmem/server.log                # Check server logs
~/.ironmem/bin/ironmem server            # Run manually to see errors

Observations not being recorded:

ironmem status                           # Check observation count
sqlite3 ~/.ironmem/mem.db "SELECT count(*) FROM observations;"

If count stays at 0, your hooks may not be installed. Re-run ./install.sh or check that ~/.claude/hooks/post-tool-use.sh exists and is executable.

Compression failing (memories always 0):

```bash