ramem

# ramem (RAM) — AI Agent Memory [](https://github.com/planetf1/ramem/actions/workflows/ci.yml) [](https://crates.io/crates/ramem) [](LICENSE) **Your AI coding agent finally remembers things.** RAM indexes your Claude Code (and other assistant) session transcripts into a local hybrid search database and gives the agent access to that history via MCP — so architectural decisions, bug patterns, and project conventions persist across sessions automatically. No cloud. No daemons. No external services. A single `ram` binary, ~640 KB, that runs entirely on your machine. ## Features - **Zero infrastructure** — embedded [LanceDB](https://lancedb.com), local ONNX embeddings (80–274 MB depending on config), no external services - **Hybrid search** — weighted BM25 + vector similarity fused via RRF, cross-encoder reranking enabled by default - **Temporal decay** — recent memories rank higher; configurable half-life (default 30 days) - **Single binary** — one `ram` executable handles MCP server, indexer, CLI, and hooks - **Automatic indexing** — file watcher indexes new transcript content with a 5-minute cooldown on active sessions - **Explicit memorization** — agents can write permanent memories via the `memorize` MCP tool - **Async enrichment** — optional background classifier enriches tags and metadata without blocking - **OpenTelemetry** — traces and metrics exported to any OTLP endpoint - **CLI parity** — every MCP capability is also available as a CLI command with `--output json` ## Use Cases ### Architectural Decisions **Without RAM:** ``` You (Day 1): "Let's use LanceDB for the vector store" Claude: "Good choice! I'll implement it." [implements LanceDB integration] You (Day 5, new session): "Why did we choose LanceDB?" Claude: "I don't have context from previous sessions. Can you remind me?" ``` **With RAM:** ``` You (Day 1): "Let's use LanceDB for the vector store" Claude: "Good choice! I'll implement it." [Claude calls memorize: "Chose LanceDB over Qdrant because..."] You (Day 5, new session): "Why did we choose LanceDB?" Claude: "Based on our decision from 4 days ago, we chose LanceDB because it embeds in-process with no daemon, has native BM25 support, and..." ``` ### Bug Pattern Recognition **Without RAM:** ``` You (Week 1): "The async task is panicking" Claude: [debugs, finds root cause, fixes] You (Week 3): "Different async task is panicking" Claude: [starts from scratch, doesn't remember similar bug] ``` **With RAM:** ``` You (Week 1): "The async task is panicking" Claude: [debugs, finds root cause, fixes] You (Week 3): "Different async task is panicking" Claude: "This looks similar to the issue we fixed 2 weeks ago where the Arc clone was inside the closure. Let me check if..." [applies same fix pattern] ``` ### Project Conventions **Without RAM:** ``` You: "Use thiserror for library errors" Claude: [implements with thiserror] [New session] You: "Add error handling to this function" Claude: [uses anyhow instead of thiserror] You: "No, we use thiserror in libraries" Claude: "Sorry, I'll fix that" ``` **With RAM:** ``` You: "Use thiserror for library errors" Claude: [implements with thiserror] [Claude calls memorize: "Convention: thiserror for libraries, anyhow for binaries"] [New session] You: "Add error handling to this function" Claude: "Based on our project convention, I'll use thiserror since this is library code..." ``` ### Cross-Project Learning **Without RAM:** ``` [Project A] You: "How do we handle rate limiting?" Claude: [implements solution] [Project B, new session] You: "How do we handle rate limiting?" Claude: [implements different solution, doesn't remember Project A] ``` **With RAM (global scope):** ``` [Project A] You: "How do we handle rate limiting?" Claude: [implements solution] [Claude calls memorize with scope="global"] [Project B] You: "How do we handle rate limiting?" Claude: "I remember we implemented a token bucket rate limiter in Project A. Would you like me to use the same pattern here?" ``` ### When to Use RAM **Good fit:** - Multi-session projects where context accumulates over days/weeks - Projects with explicit architectural decisions worth remembering - Teams with coding conventions that agents should follow - Cross-project pattern reuse (with global scope) **Not needed:** - Single-session throwaway scripts - Projects where all context fits in a single prompt - When you prefer agents to start fresh each session ## Supported AI Coding Assistants | Assistant | MCP Support | Transcript Indexing | Notes | |-----------|-------------|---------------------|-------| | **Claude Code** | ✅ Full | ✅ Automatic | All platforms; subagent sessions indexed | | **OpenCode** | ⚠️ TBD | ✅ Automatic | SQLite DB polled every 5 min | | **IBM Bob** | ❌ CLI only | ✅ Automatic | Native format + VS Code extension | | **Cline / Roo Cline** | ❌ CLI only | ✅ Automatic | VS Code globalStorage layout | | **OpenAI Codex** | ❌ CLI only | ✅ Automatic | | | **Zed** | ❌ CLI only | ✅ Automatic | Markdown conversation format | | **Aider** | ❌ CLI only | ✅ Automatic | Chat history indexing | | **Cursor** | ❌ Not yet | ❌ | Parser not implemented | | **GitHub Copilot** | ❌ Not yet | ❌ | Parser not implemented | **Legend:** - ✅ Full: Complete MCP integration with all tools available - ⚠️ TBD: MCP support status unclear, check integration guide - ❌ CLI only: No MCP support, use `ram search` / `ram memorize` from the terminal ## Installation ### Prebuilt Binaries (Recommended) Download the latest release for your platform: ```bash # macOS / Linux (via install script) curl -sSf https://github.com/planetf1/ramem/releases/latest/download/ramem-installer.sh | sh # Or download manually from: # https://github.com/planetf1/ramem/releases ``` The `ram` binary is approximately **640 KB** (static build). Embedding models (~80 MB total) are downloaded on first run by fastembed. **Resource usage at runtime:** RAM uses a smart daemon model: the first `ram serve` call starts one real daemon process; subsequent calls from other sessions attach as lightweight stdio proxies (~11 MB each). Only the daemon loads the models and the LanceDB index. Daemon RSS breakdown with default config (`BGESmallENV15` + `JinaRerankerV1TurboEn` reranker enabled): | Component | Approx RSS | |-----------|-----------| | Embedding model in ORT (`BGESmallENV15`, 128 MB on disk) | ~250 MB | | Reranker model in ORT (`JinaRerankerV1TurboEn`, 146 MB on disk) | ~280 MB | | LanceDB Arrow buffers (scales with index size) | ~2–4× on-disk size | | Tokio runtime + allocator overhead | ~50 MB | A typical installation with 100 K+ indexed chunks and both models loaded lands around **1–2 GB RSS** — this is expected, not a leak. **To reduce memory footprint:** - **Disable the cross-encoder reranker** (saves ~280 MB, biggest single change): ```toml [search] reranker_enabled = false ``` - **Reduce the reranker candidate pool** (less Arrow allocation per query, saves ~100–200 MB at peak): ```toml reranker_candidate_pool = 20 # default is 50 ``` - **Use a smaller embedding model** (`AllMiniLML6V2`, 80 MB on disk vs 128 MB): ```toml [embedding] model = "AllMiniLML6V2" ``` After changing the model run `ram wipe && ram init` to re-index. - **Use an external embedding server** (no ONNX runtime in-process, ~50 MB for the daemon): ```toml [embedding] backend = "local_api" local_api_url = "http://127.0.0.1:8095/v1" local_api_model = "your-model" ``` - **Prune the index** — a large number of indexed chunks (check with `ram status`) drives LanceDB memory use. Run `ram wipe && ram init` after narrowing `index.transcript_paths` to recent content. ### Homebrew (macOS / Linux) ```bash brew install planetf1/tap/ramem ``` ### crates.io ```bash cargo install ramem ``` ### From Source ```bash # Or build from source git clone https://github.com/planetf1/ramem cd ramem cargo build --release # binary at target/release/ram ``` ## Quick Start Choose your AI coding assistant for detailed setup instructions: - **[Claude Code](docs/integrations/claude-code.md)** — Full MCP integration with automatic hooks - **[OpenCode](docs/integrations/opencode.md)** — Transcript indexing with potential MCP support - **[Zed](docs/integrations/zed.md)** — CLI-based workflow with markdown conversation parsing - **[Aider](docs/integrations/aider.md)** — CLI-based workflow with chat history indexing ### General Setup (All Assistants) #### 1. Initialize (index existing transcripts + start watcher) ```bash ram init ``` This scans well-known transcript locations, indexes existing content, and starts a background file watcher. #### 2. Search from the terminal ```bash ram search "how did we fix the async error" ram search "lancedb schema decisions" --output json ``` #### 3. Configure MCP (if supported) See your assistant's integration guide for MCP server configuration. ## MCP Tools Once connected as an MCP server, the following tools are available to the agent: ### `search_memory` Search indexed memories using hybrid BM25 + semantic similarity with temporal decay. | Parameter | Type | Description | |-----------|------|-------------| | `query` | `string` | Natural language query | | `limit` | `integer?` | Max results (default 5, max 50) | | `scope` | `string?` | Filter by scope (`global`, `project:<name>`) | | `source` | `string?` | Filter by `indexed` or `explicit` | ### `memorize` Store an explicit memory entry directly (bypasses passive indexing). | Parameter | Type | Description | |-----------|------|-------------| | `concept` | `string` | Content to store | | `tags` | `string[]` | Classification tags | | `importance` | `float?` | 0.0–1.0, default 0.8 | ## CLI Reference ``` ram init Scan well-known locations, bulk-index, set up watcher ram serve Start MCP stdio server ram index Index transcripts (--watch for continuous, --path for custom dir) ram search <query> Search memories (--limit N, --scope S, --output json|text) ram memorize <text> Store explicit memory (--tags t1,t2 --importance 0.9) ram status Index statistics and config summary (--output json|text) ram backup Create dated .tar.gz snapshot (--dest <dir>) ram restore Restore from snapshot (--file <path>) ram config show Print current configuration ram config set Update a configuration key ram hook Claude Code hook handlers (session-start, post-tool-use, session-end) ``` ## Configuration Configuration file: `~/.config/ram/config.toml` ```toml [embedding] backend = "fastembed" # fastembed | local_api | auto model = "AllMiniLML6V2" # ~80 MB, downloads on first run init_timeout_secs = 300 # Timeout for model download (default: 5 minutes) embed_timeout_secs = 30 # Timeout for individual embed operations (default: 30 seconds) [search] rrf_k = 60 # Reciprocal Rank Fusion constant decay_half_life_days = 7.0 [augmentation] enabled = true llm_endpoint = "" # optional: Ollama/MLX URL for richer classification [otel] endpoint = "" # OTLP gRPC endpoint; empty = disabled ``` See `docs/spec.md` for the full configuration reference. ## Using a Local Embedding Server (MLX / Ollama) For better embedding quality on Apple Silicon, point RAM at a local MLX or Ollama server: ```toml [embedding] backend = "local_api" local_api_url = "http://127.0.0.1:8095/v1" local_api_model = "qwen3-embedding" ``` Any OpenAI-compatible `/v1/embeddings` endpoint works. ## Transcript Locations RAM automatically discovers transcripts in: | Platform | Path | |----------|------| | macOS / Linux | `~/.claude/projects/**/*.jsonl` | | macOS (legacy) | `~/Library/Application Support/claude-code/transcripts/**/*.jsonl` | | Linux (legacy) | `~/.local/share/claude-code/**/*.jsonl` | Additional paths can be added via `ram config set index.transcript_paths '["/extra/path"]'`. ## Documentation - **[FAQ](docs/FAQ.md)** — Frequently asked questions about privacy, performance, and usage - **[Technical Specification](docs/spec.md)** — Authoritative requirements, schema, and API reference - **[Architecture](docs/architecture.md)** — Threading model, dataflow, concurrency, and failure domains - **[Troubleshooting](docs/troubleshooting.md)** — Common issues and solutions - **[Comparisons](docs/comparisons.md)** — How RAM compares to other memory systems ## Community We welcome contributions from the community! Please review our community guidelines: - **[Contributing Guide](CONTRIBUTING.md)** — Development setup, code standards, and PR workflow - **[Code of Conduct](CODE_OF_CONDUCT.md)** — Community standards and enforcement - **[Security Policy](SECURITY.md)** — How to report vulnerabilities For technical implementation details, see `AGENTS.md`. ## Related Projects RAM is positioned against a real ecosystem of memory / transcript-indexing tools. See [`docs/comparisons.md`](docs/comparisons.md) for a full table covering Anthropic's official offerings, community projects (`rmcp-memex`, `opencode-memsearch`, `code-session-memory`, etc.), and state-of-the-art agent memory systems (Zep, Mem0, Letta, Cognee). ## License Apache-2.0