mnemo-mcp

Structured fact memory MCP server for AI coding assistants.

What It Does

mnemo-mcp is a persistent, structured memory layer that AI coding assistants can use to remember facts across sessions. It stores facts in a local SQLite database with full-text search (FTS5), trust scoring, entity graph extraction, contradiction detection, and bilingual (English/Chinese) retrieval.

Key features:

• SQLite + FTS5 -- fast full-text search with automatic index sync
• Trust scoring -- facts gain or lose trust over time based on feedback and decay
• Entity graph -- automatic entity extraction with multi-hop relationship queries
• Contradiction detection -- finds conflicting facts and demotes the older one
• Bilingual retrieval -- Chinese bigram tokenization + automatic CN/EN term expansion
• Auto-dedup -- three-layer deduplication (entity overlap, Jaccard similarity, containment) prevents duplicate facts

Installation

npm install -g mnemo-mcp

Or run without installing:

npx mnemo-mcp

Configuration

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "mnemo": {
      "command": "npx",
      "args": ["mnemo-mcp"]
    }
  }
}

Codex

Add to your Codex configuration:

{
  "mcpServers": {
    "mnemo": {
      "command": "npx",
      "args": ["mnemo-mcp"]
    }
  }
}

Tools

fact_store

The primary tool for reading and writing structured facts. Supports 9 actions:

| Action | Description | Key Parameters | |--------|-------------|----------------| | add | Add a new fact (auto-deduplicates; merges if similar exists) | content (required), category, tags | | search | Keyword search with FTS5 + Jaccard reranking | query (required), category, min_trust, limit | | probe | Find all facts about a specific entity | entity (required), min_trust, limit | | related | Find facts related to an entity through shared context | entity (required), min_trust, limit | | reason | Multi-entity reasoning: find facts connected to all given entities | entities (required), min_trust, limit | | contradict | Detect pairs of facts that share entities but conflict in content | limit | | update | Update an existing fact's content, tags, category, or trust score | fact_id (required), content, tags, category, trust_delta | | remove | Delete a fact by ID | fact_id (required) | | list | Browse facts sorted by trust score | category, min_trust, limit |

Common parameters:

• category -- filter by fact category (see Categories below)
• min_trust -- minimum trust score threshold (default: 0.3)
• limit -- maximum number of results (default: 10)
• tags -- comma-separated tags for classification

fact_feedback

Rate a fact after use. Good facts rise, bad facts decay.

| Action | Description | |--------|-------------| | helpful | Mark fact as accurate (+0.05 trust) | | unhelpful | Mark fact as outdated or wrong (-0.10 trust) |

Parameters:

• fact_id (required) -- the fact to rate

Architecture

+-------------------+    stdio    +------------+    better-sqlite3    +-----------------------+
|   MCP Client      | <--------> | mnemo-mcp  | <------------------> | ~/.mnemo/facts.db     |
| (Claude / Codex)  |    JSON    |  server    |     SQLite + FTS5    |                       |
+-------------------+            +------------+                      |  tables:              |
                                        |                           |    facts              |
                                        |                           |    entities           |
                                 +------+------+                    |    fact_entities      |
                                 |             |                    |  indexes:             |
                                 | Retriever   | Security          |    facts_fts (FTS5)   |
                                 | (search,    | (PII scan,        |    idx_facts_trust     |
                                 |  probe,     |  injection        |    idx_facts_category  |
                                 |  reason)    |  detection)       +-----------------------+
                                 +-------------+

Data directory: ~/.mnemo/facts.db (created automatically on first run).

Categories

Facts are organized into categories that control decay rates and retrieval behavior:

| Category | Description | Grace Period | Decay Rate | |----------|-------------|--------------|------------| | identity | User identity: name, role, preferences | 60 days | 0.02/week | | coding_style | Coding conventions, naming rules, formatting | 30 days | 0.03/week | | tool_pref | Tool and framework preferences | 30 days | 0.03/week | | workflow | Development workflow, CI/CD, git practices | 45 days | 0.02/week | | general | General knowledge and other facts | 30 days | 0.03/week |

When writing facts, always search first to avoid duplicates. Facts below 0.1 trust are automatically removed during startup maintenance.

License

MIT