SaiMem

Local MCP (Model Context Protocol) server for persistent memory in AI agents. Give your AI agents long-term memory with zero external API dependencies.

Features

• Hybrid Search: BM25 (keyword) + cosine similarity (semantic) + graph centrality scoring for best results
• Local Embeddings: Xenova/multilingual-e5-small — 384d vectors, no API keys, no network calls
• Intelligent Recall: Context-aware retrieval with intent classification, topic expansion, and token budget management
• Duplicate Detection: Structural + semantic dedup with automatic near-duplicate merging
• Knowledge Graph: Track relationships (supersedes, implements, contradicts, co_tagged, related_to) between memories
• 22 Agent Platforms: saicode, claude-code, copilot, cursor, windsurf, cline, continue, kilo-code, antigravity, zed, codex-cli, gemini-cli, augment, crush, trae, opencode, qwen-code, codebuddy, factory-droid, iflow, paicode, coplay
• Lifecycle Management: Auto-extraction, summarization, relationship linking, tier-based expiry, and consolidation
• Webview UI: Built-in database manager, knowledge graph visualization, statistics, audit log
• Quality Scoring: Warns on noise-level content, auto-prunes ephemeral memory
• Zero Config: Auto-initializes database in your project, works out of the box

Quick Start

npm install -g saimem

saimem setup

# Restart your agent - SaiMem will automatically provide context

MCP Tools

| Tool | Description | |------|-------------| | memory_save | Save knowledge with auto type detection, dedup, and quality scoring | | memory_search | Hybrid search with BM25 + cosine + graph scoring, knowledge gap tracking | | memory_recall | Context bundle with intent classification, topic expansion, index/full mode | | memory_manage | 12 actions: update, delete, restore, link, unlink, boost, promote, session_end, mark_outdated, mark_irrelevant, history | | memory_graph | Traverse relationship edges with depth control (1-3) | | memory_status | Database statistics, embedding pipeline health, cache stats | | memory_list | Paginated browsing with type/tags/date filters | | memory_reflect | Health checks (orphans, stales, gaps) and periodic digests | | memory_detail | Fetch full content by UUID with access tracking |

CLI Commands

saimem [command]

Commands:
  serve                  Start MCP server (default)
  wrapper                Smart workspace auto-detection for Global MCP
  ui [--port]            Webview UI (default port 3737)
  hook <event>           Agent hook events (session_start, pre_compact, etc.)
  setup [platform]       Configure agent integration
  init daemon            Install background maintenance scheduler
  status                 Project memory statistics
  backup [path]          Backup database
  vacuum                 Optimize database
  reset --force          Delete all memories
  doctor [path]          System health diagnostics
  consolidate            Merge and consolidate memories
  maintain [--full]      Run all maintenance tasks
  clean-noise [--dry-run] Remove low-value memories
  embed-backlog          Process memories missing embeddings
  extract-backlog        Process entity extraction queue
  migrate-project <id>   Migrate orphaned project_ids
  --version              Show version
  --help                 Show help

Configuration

Database: .saicode/databases/memory.db in your project root.

Config file (~/.saicode/saimem-config.json):

{
  "graph": { "provider": "kuzu" },
  "llm": {
    "provider": "ollama",
    "model": "qwen2.5:3b",
    "baseUrl": "http://localhost:11434",
    "rateLimit": 10,
    "timeout": 60000
  }
}

LLM providers: openai, anthropic, or ollama. Used for entity extraction and summarization.

Environment variables:

| Variable | Description | |----------|-------------| | SAIMEM_DB_PATH | Custom database path | | SAIMEM_PROJECT_ID | Override project identifier | | SAIMEM_LOG_LEVEL | debug, info, warn, error (default: info) | | SAIMEM_WEBVIEW_PUBLIC | Webview static assets path | | SAICODE_LLM_PROVIDER | LLM backend (openai/anthropic/ollama) | | SAICODE_LLM_MODEL | Model name | | SAICODE_LLM_API_KEY | API key | | SAICODE_GRAPH_PROVIDER | Graph backend (sqlite/kuzu) |

Memory Types

| Type | Description | |------|-------------| | Semantic | General knowledge and information | | Episodic | Events, bugs, incidents that happened | | Procedural | How-to guides, steps, processes | | Decision | Architecture decisions, trade-offs made |

Each memory has an importance level (low/medium/high/critical) and a tier that controls its lifespan:

• Tier 0 (permanent): Critical memories, never expires
• Tier 1 (stable): High importance, 2-year TTL
• Tier 2 (working): Medium importance, 1-year TTL
• Tier 3 (ephemeral): Low importance/noise, 7-day TTL, auto-pruned

Recall Protocol

memory_recall(topic=<2-4 keywords>) → loads relevant context
memory_recall(mode='index') → compact metadata-only index (≤1500 tokens)
memory_detail(uuid) → fetch full content

• Intent classification skips trivial/command messages to save tokens
• Topic expansion adds synonyms (English + Vietnamese) for broader matching
• 2-layer caching: In-memory LRU (30s) + SQLite recall cache (5 min, survives restart)
• Importance-weighted budget scales up for projects with many high/critical memories
• Session delta avoids re-injecting already-seen memories

Webview UI

saimem ui           # Opens http://localhost:3737
saimem ui --port 8080

• Database manager with search, filter, pagination
• Knowledge graph visualization (Cytoscape.js): interactive node selection, multiple layouts, export to PNG/SVG/JSON/Mermaid
• Statistics dashboard with type distribution and tag frequency
• Audit log tracking all operations
• Bulk operations: delete, export JSON/CSV
• Import/Export: drag-and-drop JSON/CSV files
• Tag hierarchy browser (dot notation: frontend.react)
• Dark/light theme toggle
• Real-time SSE notifications
• Keyboard shortcuts (/ search, j/k navigate, ? help)

Background Workers

SaiMem runs these maintenance workers automatically:

• Embedding queue: Batch vector generation (32/batch), 5s poll
• Entity extractor: LLM-powered entity extraction, 2s poll
• Summary worker: Async content summarization, 7s poll
• Auto-link worker: Relationship building from shared tags + semantic similarity, 3s poll
• Consolidation scheduler: Auto-consolidation every 6 hours
• Reflection engine: Auto-reflect every 10 sessions
• Memory pruner: Remove expired tier-3 memories

Development

git clone https://github.com/supermeo/saimem.git
cd saimem/saimem

npm install
npm run build
npm test
npm run test:coverage

License

MIT