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

One command. No dependencies for pre-built binaries. Three installation methods.

curl -fsSL https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.sh | sh

irm https://raw.githubusercontent.com/alphaonedev/ai-memory-mcp/main/install.ps1 | iex

cargo install ai-memory

docker build -t ai-memory .
docker run -p 9077:9077 -v data:/data ai-memory

cargo binstall ai-memory

1. Optional: Ollama for Smart & Autonomous tiers Optional

   The keyword and semantic tiers work with zero dependencies. The smart and autonomous tiers add LLM-powered query expansion, auto-tagging, and neural reranking via Ollama.

2. 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.

3. Configure your AI platform

   Choose the integration method that fits your setup.

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

   Claude Code MCP Configuration Scopes:

   Scope	File	Applies to
   User (global)	~/.claude.json	All projects on your machine
   Project (shared)	.mcp.json in project root	Everyone on the project (via git)
   Local (private)	~/.claude.json under projects	One project, just you

   User scope (recommended) — merge mcpServers into your existing ~/.claude.json (macOS/Linux) or %USERPROFILE%\.claude.json (Windows):

   {
     "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. MCP servers do not go in settings.json or settings.local.json. The --tier flag is required — options: keyword, semantic (default), smart, autonomous. Smart/autonomous require Ollama.

   Windows: Use ai-memory.exe for the command and forward slashes in paths: "C:/Users/YourName/.claude/ai-memory.db"

   OpenAI Codex CLI Configuration Scopes:

   Scope	File	Applies to
   Global (user)	~/.codex/config.toml	All projects on your machine
   Project	.codex/config.toml in project root	Trusted projects only

   Windows: %USERPROFILE%\.codex\config.toml. Override config dir with CODEX_HOME env var.

   # 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 uses TOML with underscored key mcp_servers (not camelCase). Supports env, env_vars, enabled_tools, disabled_tools, startup_timeout_sec, tool_timeout_sec. Use /mcp in the TUI to view server status. Windows/WSL: WSL uses Linux home by default — set CODEX_HOME to share config with Windows host. See Codex MCP docs.

   Google Gemini CLI Configuration Scopes:

   Scope	File	Applies to
   User (global)	~/.gemini/settings.json	All projects on your machine
   Project	.gemini/settings.json in project root	Scoped to that project

   Windows: %USERPROFILE%\.gemini\settings.json. Env vars: $VAR / ${VAR} (all platforms), %VAR% (Windows).

   {
     "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>. Env vars in env field support $VAR / ${VAR} (all platforms) and %VAR% (Windows). Gemini sanitizes sensitive patterns (*TOKEN*, *SECRET*) from inherited env unless declared. Add "trust": true to skip confirmation. CLI: gemini mcp list/remove/enable/disable. See Gemini CLI MCP docs.

   Cursor IDE Configuration Scopes:

   Scope	File	Applies to
   Global (user)	~/.cursor/mcp.json	All projects on your machine
   Project	.cursor/mcp.json in project root	Overrides global for same-named servers

   Windows: %USERPROFILE%\.cursor\mcp.json. Also configurable via Settings > Tools & MCP.

   {
     "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_NAME} interpolation (can be unreliable for shell profile vars — use envFile as workaround). ~40 tool limit across all servers. See Cursor MCP docs.

   Windsurf (Codeium) Configuration Scopes:

   Scope	File	Applies to
   Global only	~/.codeium/windsurf/mcp_config.json	All projects (no project scope)

   Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Also configurable via MCP Marketplace or Settings > Cascade > MCP Servers.

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

   Supports ${env:VAR_NAME} interpolation in command, args, env, serverUrl, url, and headers. 100 tool limit across all servers. Can also add via MCP Marketplace or Settings > Cascade > MCP Servers. See Windsurf MCP docs.

   Continue.dev Configuration Scopes:

   Scope	File	Applies to
   User (global)	~/.continue/config.yaml	All projects on your machine
   Project	.continue/mcpServers/ dir in project root	Per-server YAML/JSON files

   Windows: %USERPROFILE%\.continue\config.yaml. Project dir auto-detects JSON configs from other tools.

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

   MCP tools only work in agent mode. Supports ${{ secrets.SECRET_NAME }} for secret interpolation. Project-level .continue/mcpServers/ directory auto-detects JSON configs from other tools (Claude Code, Cursor, etc.). See Continue MCP docs.

   xAI Grok Configuration:

   Scope	Method	Applies to
   Per-request	API tools array (no config file)	Each API call individually

   Remote HTTPS 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. Optional: allowed_tools, authorization, headers. Works with xAI SDK, OpenAI-compatible Responses API, and Voice Agent API. See xAI Remote MCP docs.

   META Llama Stack Configuration:

   Scope	Method	Applies to
   Declarative	run.yaml — tool_groups section	Deployment-wide (supports ${env.VAR})
   Programmatic	Python/Node SDK — toolgroups.register()	Runtime registration

   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 as a toolgroup via Python SDK or run.yaml (supports ${env.VAR_NAME} interpolation). Transport migrating from SSE to Streamable HTTP. See Llama Stack Tools docs.

   OpenClaw Configuration:

   Scope	File	Applies to
   Single config	Platform config file	All projects (single config file)

   Important: OpenClaw uses mcp.servers (NOT mcpServers). The key structure is different from most other platforms.

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

   CLI shortcut:

   openclaw mcp set memory '{"command":"ai-memory","args":["--db","~/.local/share/ai-memory/memories.db","mcp","--tier","semantic"]}'bash

   Management: openclaw mcp list · openclaw mcp show <name> · openclaw mcp unset <name>. See OpenClaw MCP docs.

   Generic MCP Client Configuration:

   Transport	Method	Details
   stdio	ai-memory mcp	JSON-RPC 2.0, spawned by AI client
   HTTP	ai-memory serve	REST API on localhost:9077

   Point your MCP client at the ai-memory binary with the mcp subcommand:

   {
     "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.

4. 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.

25 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.