Iron Mem
Persistent session memory for AI coding assistants. IronMem silently records your coding sessions, compresses them into concise memories via Claude API, and injects context into your next session automatically. Works with Claude Code, Cursor, Copilot, and Windsurf. Local-first single Rust binary.
Ask AI about Iron Mem
Powered by Claude Β· Grounded in docs
I know everything about Iron Mem. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Persistent memory for AI coding assistants.
Stop re-explaining your project every time you start a new session.
Install β’ How It Works β’ CLI β’ Multi-Provider β’ Contributing
What's New in v0.3.0
Now multi-provider, cross-platform, with a built-in web UI.
- 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.
v0.2.0
- 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 upfor 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, or Google 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. Plain markdown output. 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
- Install IronMem:
curl -fsSL https://raw.githubusercontent.com/BMC-INC/Iron-mem/main/install.sh | bash - Add your API key (in your
~/.zshrcor~/.bashrc):export ANTHROPIC_API_KEY="your-key-here" - Start coding! IronMem handles the rest silently in the background.
Table of Contents
- Quick Start
- The Problem
- The Fix
- Who Should Use This?
- How It Works
- Install
- CLI
- Multi-Provider Support
- MCP Setup
- Web UI
- Configuration
- Troubleshooting
- Architecture
- Why Rust?
- Design Principles
- Why not just use CLAUDE.md?
- Roadmap
- Contributing
- Support
- License
The Problem
Every time you start a new session with Claude Code, Cursor, Copilot, or any AI coding assistant β it starts from zero. It doesn't know what you built yesterday. It doesn't know what broke. It doesn't know 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 into a concise memory using your LLM provider of choice (Anthropic, OpenAI, or Gemini), 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.
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 to your shell profile (~/.zshrc or ~/.bashrc):
export PATH="$HOME/.ironmem/bin:$PATH"
export ANTHROPIC_API_KEY="your-key-here"
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" # Full-text 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
ironmem compress <id> # Manually compress a session
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 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 memoriessearch_globalβ search across all projectslist_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.
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:
- Starts the SSE server with no auth
- Launches a Cloudflare Tunnel (free, no account needed) to expose it publicly
- 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:
- Open
Settings - Open
Integrations - Choose
Add custom connector - Set
NametoIronMem - Paste the printed
https://...trycloudflare.com/mcpURL intoRemote MCP server URL - 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 and only when you understand that you are trading security for compatibility.
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 (brew install cloudflared on macOS, winget install Cloudflare.cloudflared on Windows). Falls back to npx cloudflared if 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
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 |
Web UI
When the REST server is running, a built-in memory browser is available at:
http://localhost:37778/ui
The UI shows sessions, memories, and database stats. You can browse, search, and delete memories directly from the browser.
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
}
All fields optional. Sensible defaults provided. auth_token is generated automatically the first time you run ironmem serve without --no-auth.
Provider
IronMem supports three LLM providers for session compression:
| Provider | provider value | Default model | API key env var |
|---|---|---|---|
| Anthropic | "anthropic" | claude-sonnet-4-6-20250627 | ANTHROPIC_API_KEY |
| OpenAI | "openai" | gpt-4o | OPENAI_API_KEY |
| Google Gemini | "google" | gemini-2.0-flash | GOOGLE_API_KEY |
To switch providers, set "provider" in ~/.ironmem/settings.json and ensure the corresponding API key is set. The model field overrides the provider's default model.
Environment Variables
| Variable | Default | Description |
|---|---|---|
DATABASE_URL | (none) | Postgres URL. Overrides db_path when set. |
IRONMEM_MCP_TRANSPORT | stdio | MCP transport: stdio or sse |
ANTHROPIC_API_KEY | (none) | Required when provider is anthropic (default) |
OPENAI_API_KEY | (none) | Required when provider is openai |
GOOGLE_API_KEY | (none) | Required when provider is google |
API Key
IronMem needs an LLM API key to compress session observations into memories. Set the environment variable for your chosen provider (ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY).
For the default Anthropic provider, IronMem also checks ~/.ironmem/api_key as a fallback. This file is auto-created by the session-start hook because the IronMem server runs as a background process via nohup, and some environments strip environment variables from child processes. The hook persists your API key with chmod 600 permissions so the server can always access it.
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):
# Check if the API key is accessible
cat ~/.ironmem/api_key # Should contain your key
echo $ANTHROPIC_API_KEY # Should be set
# Try manual compression
ironmem compress <session-id> # Get session ID from server.log
Hooks not firing:
Check that ~/.claude/settings.json has the hooks registered under the "hooks" key. Re-running ./install.sh will fix this.
Architecture
~/.ironmem/
βββ bin/ironmem # Single compiled binary
βββ mem.db # SQLite database (FTS5 full-text search)
βββ settings.json # Configuration
βββ api_key # Anthropic API key (auto-persisted, chmod 600)
βββ current_session # Active session ID (ephemeral)
βββ server.log # Worker logs
~/.claude/hooks/ # Auto-installed Claude Code hooks
βββ session-start.sh # Injects memories on session start
βββ post-tool-use.sh # Records every tool call
βββ stop.sh # Triggers compression
βββ session-end.sh # Cleanup
~2,400 lines of Rust. MCP-native. SQLite or Postgres. One binary. No external runtimes.
Why Rust?
Rust was chosen for IronMem to deliver:
- Maximum Performance: Minimal overhead and lightning-fast execution, essential for a tool that hooks into every single CLI command.
- Zero Dependencies: Compiles down to a single binary. No need to install Python, Node.js, or complex runtime environments.
- Memory Safety & Reliability: Guaranteed safety without a garbage collector ensures the background worker remains rock-solid and leak-free.
Design Principles
- Zero friction β hooks run silently, never interrupt your workflow
- Local-first β runs on your machine by default, your data stays yours
- MCP-native β speaks the protocol every major AI client is adopting
- Provider-agnostic β MCP for native integration, plain markdown for everything else
- Self-hostable β Docker + Postgres for team deployments, still zero cloud dependencies
- Fail-safe β if IronMem crashes, your coding session is unaffected
Who this is for
IronMem is for developers who use AI coding tools heavily and want continuity across sessions.
It is especially useful if you:
- switch between Claude Code, Cursor, Copilot, or Windsurf
- work on projects that span many sessions
- are tired of re-explaining architecture, bugs, and recent changes
- want local-first memory instead of a hosted service
Who this is not for
IronMem is not trying to be:
- a generic memory platform for every kind of agent
- a cloud sync product
- a team knowledge base
- a dashboard-heavy workflow tool
It solves one narrow problem well: session memory for AI coding workflows.
Why not just use CLAUDE.md?
CLAUDE.md is great for static project context β things like "use tabs not spaces" or "we use Axum for routing." But it's manual. You write it, you maintain it, and it doesn't know what happened last session.
IronMem is automatic and session-aware:
| CLAUDE.md | IronMem | |
|---|---|---|
| Updates | You write it manually | Auto-generated from session activity |
| Scope | Static project rules | Dynamic session history |
| Rotation | You manage it | Old memories age out automatically |
| Search | Ctrl+F | Full-text search across all sessions |
| Effort | High | Zero β hooks handle everything |
They work together. CLAUDE.md holds your project rules. IronMem holds what happened.
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.
Roadmap
Shipped in v0.2.0
- MCP-native server (stdio + Streamable HTTP)
- Dual database β SQLite (local, FTS5) + Postgres (self-hosted)
- Docker deployment with Postgres
- Bearer token authentication
-
ironmem serve --publicwith Cloudflare Tunnel for remote MCP clients -
ironmem serve --public --no-authfor claude.ai personal use - Works with Claude Code, Claude Desktop, Cursor, Windsurf, ChatGPT Desktop, Zed, VS Code
Shipped in v0.3.0
- Multi-provider compression β OpenAI, Google Gemini, or Anthropic (configurable via
providerin settings) - Neovim plugin (
nvim/lua/ironmem/) β auto session lifecycle,:IronMemSearch,:IronMemStatus - Windows native support β
install.ps1, platform-aware install messages, robust home dir detection - Web UI memory browser β
http://localhost:37778/uiwhen REST server is running
Contributing
Contributions are welcome. Please read CONTRIBUTING.md before opening a PR.
TL;DR: Open an issue first. Bug fixes and provider compatibility improvements are always welcome. We don't accept changes that add runtime dependencies or complexity.
β Support
If you find IronMem useful, please consider giving it a star! π This helps others discover the project and motivates further development. Contributions, issues, and feature requests are also highly welcome.
License
Apache-2.0 Β© 2026 ExecLayer Inc
Maintainer: James Benton
