Persistent Memory for Any AI

LongMemEval Benchmark (ICLR 2025) — 500 questions, 6 categories

Pure SQLite FTS5 + BM25 — zero cloud dependencies — full benchmark details & replication steps

Install

Grab the binary, optionally install Ollama for advanced tiers, configure your AI platform, and go.

1. Quick install (pre-built binary)

   Download the latest release for your platform. No build tools required.

   macOS / Linux

   curl -fsSL https://github.com/alphaonedev/ai-memory-mcp/releases/latest/download/install.sh | sh

   Detects your OS and architecture automatically. Installs to ~/.local/bin/ (add to PATH if not already).

   Windows

   irm https://github.com/alphaonedev/ai-memory-mcp/releases/latest/download/install.ps1 | iex

   Run in PowerShell. Installs to %LOCALAPPDATA%\ai-memory\ and adds it to your PATH.

   The keyword and semantic tiers work immediately with zero additional dependencies.

2. Build from source (alternative)

   Clone the repo and compile. You need Rust, a C compiler, and pkg-config installed.

   git clone https://github.com/alphaonedev/ai-memory-mcp.git
   cd ai-memory-mcp
   cargo install --path .bash

   This installs the ai-memory binary to ~/.cargo/bin/. On Debian/Ubuntu, install build deps with sudo apt install build-essential pkg-config. On macOS, Xcode Command Line Tools provides everything needed.

3. Install Ollama Smart & Autonomous Tiers

   The smart and autonomous tiers use local LLMs via Ollama for query expansion, auto-tagging, contradiction detection, and cross-encoder reranking. Skip this step if you only need keyword or semantic search.

   macOS

   # Install via Homebrew
   brew install ollama
   
   # Or download the macOS app:
   # https://ollama.com/download/mac
   
   # Start the Ollama service
   ollama serve &
   # (or launch the Ollama.app -- it runs as a menu bar item)
   
   # Pull models for your tier
   ollama pull nomic-embed-text  # Embeddings (smart+)
   ollama pull gemma4:e2b         # LLM — Smart (~1GB)
   ollama pull gemma4:e4b         # LLM — Autonomous (~2.3GB)

   Linux

   # One-line install script
   curl -fsSL https://ollama.com/install.sh | sh
   
   # Enable and start the systemd service
   sudo systemctl enable ollama
   sudo systemctl start ollama
   
   # Pull models for your tier
   ollama pull nomic-embed-text  # Embeddings (smart+)
   ollama pull gemma4:e2b         # LLM — Smart (~1GB)
   ollama pull gemma4:e4b         # LLM — Autonomous (~2.3GB)

   Windows

   # Install via winget
   winget install Ollama.Ollama
   
   # Or download the installer:
   # https://ollama.com/download/windows
   
   # Ollama runs as a system service after install
   
   # Pull models for your tier
   ollama pull nomic-embed-text  # Embeddings (smart+)
   ollama pull gemma4:e2b         # LLM — Smart (~1GB)
   ollama pull gemma4:e4b         # LLM — Autonomous (~2.3GB)

   Verify Ollama

   # Check Ollama is running and models are available
   curl http://localhost:11434/api/tags
   ollama run gemma4:e2b "Hello, world"   # Should respond in ~1s

   ai-memory connects to Ollama at localhost:11434 automatically. Override with ollama_url in ~/.config/ai-memory/config.toml or --ollama-url flag. If Ollama is unavailable, ai-memory gracefully falls back to the semantic tier.

4. Configure your AI platform

   Choose the integration method that fits your setup.

   Claude Code Codex CLI Gemini CLI Cursor Windsurf Continue.dev Grok Llama Any MCP Client

   Config: ~/.claude/.mcp.json (global config -- memory works across all projects)

   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "~/.claude/ai-memory.db", "mcp", "--tier", "semantic"]
       }
     }
   }json

   Restart Claude Code. It will discover all 17 memory tools natively. No daemon, no ports. Do not place this in settings.json or project-level .mcp.json -- memory is a global service. The --tier flag is required -- options: keyword, semantic (default), smart, autonomous. Smart/autonomous require Ollama.

   Config: ~/.codex/config.toml (global) or .codex/config.toml (project)

   # OpenAI Codex CLI MCP configuration
   [mcp_servers.memory]
   command = "ai-memory"
   args = ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
   enabled = truetoml

   CLI shortcut: codex mcp add memory -- ai-memory --db ~/.local/share/ai-memory/memories.db mcp --tier semantic

   Codex CLI uses TOML config. Use enabled_tools to restrict which memory tools are exposed. Use /mcp in the TUI to view server status. Supports startup_timeout_sec, tool_timeout_sec, and HTTP servers via url. See Codex MCP docs.

   Config: ~/.gemini/settings.json (user) or .gemini/settings.json (project)

   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"],
         "timeout": 30000
       }
     }
   }json

   CLI shortcut: gemini mcp add memory ai-memory -- --db ~/.local/share/ai-memory/memories.db mcp --tier semantic

   Avoid underscores in server names (use hyphens). Tool names are auto-prefixed as mcp_memory_<toolName>. Gemini sanitizes env vars -- declare needed vars in env field. Add "trust": true to skip confirmation prompts. See Gemini CLI MCP docs.

   Config: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "~/.local/share/ai-memory/memories.db", "mcp", "--tier", "semantic"]
       }
     }
   }json

   Or add via Cursor Settings > Tools & MCP. Restart Cursor after editing. Verify with green dot in Settings. Supports env, envFile, ${env:VAR} interpolation. ~40 tool limit across all servers. See Cursor MCP docs.

   Config: ~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "~/.codeium/windsurf/ai-memory.db", "mcp", "--tier", "semantic"]
       }
     }
   }json

   Windsurf (by Codeium) loads MCP servers from its config directory. Restart Windsurf after editing. Tools appear in the Cascade AI panel.

   Config: ~/.continue/config.yaml

   # Continue.dev MCP configuration
   mcpServers:
     - name: memory
       command: ai-memory
       args:
         - "--db"
         - "~/.continue/ai-memory.db"
         - "mcp"
         - "--tier"
         - "semantic"yaml

   Continue.dev uses YAML configuration. Add the MCP server block to your existing config. Restart the Continue extension after saving.

   Grok connects to MCP servers over HTTPS (remote only, no stdio). Start ai-memory behind an HTTPS reverse proxy.

   # Step 1: Start the ai-memory HTTP server
   ai-memory serve --host 127.0.0.1 --port 9077 &
   # Expose via HTTPS reverse proxy (nginx, caddy, cloudflare tunnel, etc.)
   
   # Step 2: Add the MCP server to your Grok API call
   curl https://api.x.ai/v1/responses \
     -H "Authorization: Bearer $XAI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "grok-3",
       "tools": [{
         "type": "mcp",
         "server_url": "https://your-server.example.com/mcp",
         "server_label": "memory",
         "server_description": "Persistent AI memory with recall and search"
       }],
       "input": "What do you remember about our project?"
     }'bash

   HTTPS required. server_label is required. Supports Streamable HTTP and SSE transports. See xAI Remote MCP docs.

   Llama Stack uses toolgroup registration with an HTTP backend.

   # Step 1: Start the ai-memory HTTP server
   ai-memory serve --host 127.0.0.1 --port 9077 &
   
   # Step 2: Register as a Llama Stack toolgroup
   # In your Llama Stack config, register the MCP endpoint:
   #   toolgroup: ai-memory
   #   provider: remote::mcp-endpoint
   #   url: http://127.0.0.1:9077
   
   # Or use the REST API directly in custom tool definitions:
   #   POST /api/v1/memories, GET /api/v1/recall, etc.bash

   META Llama uses Llama Stack for tool registration. Run ai-memory serve and register it as a remote MCP endpoint or wrap the REST API in your toolgroup definitions.

   For any MCP-compatible client, point it to the ai-memory binary with the mcp subcommand. Standard stdio JSON-RPC config:

   {
     "mcpServers": {
       "memory": {
         "command": "ai-memory",
         "args": ["--db", "path/to/memory.db", "mcp", "--tier", "semantic"]
       }
     }
   }json

   The MCP server exposes 17 tools over stdio using JSON-RPC. Any client that speaks MCP will discover them automatically. Adjust the --db path to your preferred location.

5. Verify it works

   Check that your AI has access to memory tools.

   # MCP: Ask your AI "What memory tools do you have?"
   # HTTP: curl http://127.0.0.1:9077/api/v1/health
   # CLI:  ai-memory statstext

Feature Tiers 4 Levels

Each tier builds on the one below it. Choose based on your resources and needs. Set via ai-memory mcp --tier <name> or in ~/.config/ai-memory/config.toml.

Capability Matrix

Every capability mapped to its minimum tier. Each tier includes all capabilities from the tiers below it.

Tiers gate features, not models. The --tier flag controls which tools are exposed. The LLM model is independently configurable via llm_model in config.toml. For example, run autonomous tier (all features) with the faster e2b model: llm_model = "gemma4:e2b" (46 tok/s vs 26 tok/s for e4b). If Ollama is unavailable at startup, smart and autonomous tiers fall back to semantic automatically.

# ~/.config/ai-memory/config.toml
# Created automatically on first run with defaults commented out

tier = "autonomous"                   # keyword | semantic | smart | autonomous
db = "~/.claude/ai-memory.db"         # SQLite database path
ollama_url = "http://localhost:11434" # Ollama API endpoint
llm_model = "gemma4:e2b"             # independently configurable (e2b=46tok/s, e4b=26tok/s)
cross_encoder = true                 # Neural reranking (autonomous tier)
default_namespace = "global"         # Default namespace for new memoriestoml

17 MCP Tools Universal Integration

ai-memory runs as a Model Context Protocol (MCP) tool server over stdio. Any MCP-compatible AI client -- Claude, ChatGPT, Grok, Llama, or custom agents -- discovers these tools automatically.

24 CLI Commands Universal

Global flags: --db <path> and --json. Scriptable, pipeable, works in any shell. Use directly or wrap in your AI's tool layer.

6-Factor Recall Scoring

Every recall query computes a composite score entirely in SQLite. Higher scores rank first. No external ML or embedding service required.

Recency Decay Curve

Architecture

Single Rust binary. Three universal interfaces. Four feature tiers with optional local LLMs via Ollama.

Interactive Shell

ai-memory shell opens a REPL with color-coded output. Tiers are red/yellow/green, priority is visualized as bars, namespaces appear in cyan.

CI/CD Pipeline

GitHub Actions runs on every push and PR. Releases are automated on tag push with cross-platform binaries.