mneme

# mneme-rs Lightweight MCP server for AI agent memory — **Rust + SQLite + local embeddings**. Stores knowledge in a hierarchical context tree, supports full-text and semantic search, compiled rule enforcement, and audit logging. Runs as a single binary on stdin/stdout — zero cloud dependencies. ## Features - **12 MCP tools** — curate, query, search, batch ops, semantic search, rule enforcement, audit log, stats, GC - **SQLite WAL** — concurrent reads, crash-safe, UPSERT semantics - **Hierarchical paths** — `project/decisions/rule-001` style organization - **Full-text search** — across paths, values, and tags (FTS5) - **Semantic search** — local embeddings via [FastEmbed](https://github.com/Anush008/fastembed-rs) (AllMiniLML6V2, 384-dim) - **Batch operations** — 10-50x faster than individual calls - **Rule enforcement** — compiled anti-patterns, scope filtering, negation detection - **Audit log** — who did what, when, with action filtering - **File watcher** — auto-reload on tree changes - **GC** — orphan cleanup, audit log compaction, DB vacuum - **JSON fallback** — works without SQLite (tree saved to JSON file) ## Tools | Tool | Description | |------|-------------| | `curate` | Store context at a path with optional tags | | `curate_batch` | Store multiple entries at once (10-50x faster) | | `query` | Retrieve context by path prefix | | `query_batch` | Query multiple paths at once | | `search` | Full-text search across stored context | | `hybrid_search` | Semantic search using local embeddings (cosine similarity) | | `embed` | Generate and store embeddings for all nodes | | `enforce` | Check text against compiled architectural rules | | `compile_rules` | Load and compile a ruleset JSON file | | `get_audit_log` | Recent audit entries (who/what/when) | | `stats` | Database statistics and usage analytics | | `gc` | Garbage collection: orphan cleanup, compaction, vacuum | ## Quick Start ### Build ```bash # Requires Rust 1.80+ cargo build --release ``` Binary: `target/release/mneme-rs` (~5MB) ### Run ```bash MNEME_TREE_PATH=/data/context_tree.json \ MNEME_DB_PATH=/data/mneme.db \ MNEME_RULES_PATH=/data/rules.json \ ./target/release/mneme-rs ``` ### Hermes Agent Integration Add to `config.yaml`: ```yaml mcp: servers: mneme: command: /opt/mneme/mneme-rs env: MNEME_TREE_PATH: /opt/mneme/data/context_tree.json MNEME_DB_PATH: /opt/mneme/data/mneme.db MNEME_RULES_PATH: /opt/mneme/rules.json ``` ## Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `MNEME_TREE_PATH` | `.mneme/context_tree.json` | Path to JSON tree file | | `MNEME_DB_PATH` | `<tree_dir>/mneme.db` | SQLite database (optional, enables persistence) | | `MNEME_RULES_PATH` | — | Rules JSON file (loaded at startup) | ## Architecture ``` ┌─────────────────────────────────────────────┐ │ MCP Client │ │ (Hermes, Claude, etc.) │ └──────────────────┬──────────────────────────┘ │ stdin/stdout JSON-RPC ┌──────────────────▼──────────────────────────┐ │ mneme-rs │ │ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │ │ │ Context │ │ Enforcer │ │ Embedder │ │ │ │ Tree │ │ (rules) │ │ (FastEmbed) │ │ │ └────┬─────┘ └──────────┘ └──────┬──────┘ │ │ │ │ │ │ ┌────▼───────────────────────────▼──────┐ │ │ │ SQLite (WAL) │ │ │ │ context │ embeddings │ audit_log │ │ │ └───────────────────────────────────────┘ │ └─────────────────────────────────────────────┘ ``` ## Rules Format ```json { "meta": { "name": "my-rules", "version": "1.0.0" }, "rules": [ { "id": "no-postgresql", "type": "anti_pattern", "patterns": ["postgresql", "postgres://"], "scope": ["database"], "message": "Use SQLite for embedded storage." } ] } ``` Rule types: `rule`, `anti_pattern`, `preference`, `fact`. Scopes: `["*"]` matches all, or specific like `["database", "storage"]`. The enforcer handles negation — *"we should not use PostgreSQL"* won't trigger the anti-pattern. See `examples/rules.json` for a full ruleset. ## Performance | Operation | Throughput | |-----------|-----------| | `curate` (single) | ~10k ops/sec | | `curate_batch` (100 entries) | ~50k entries/sec | | `query` (path prefix) | ~50k ops/sec | | `search` (FTS5) | ~20k ops/sec | | `hybrid_search` (embed + cosine) | ~100 queries/sec | | Binary size | ~5MB | | RAM usage | ~15MB (with embeddings loaded) | SQLite WAL mode allows concurrent reads while writing. No external services required. ## Testing ```bash cargo test ``` Tests cover: context tree CRUD, SQLite persistence, embeddings roundtrip, cosine similarity, watcher, rule enforcement, batch operations. ## License MIT