ferrex

Local-first MCP memory server for AI agents. One Rust binary, a Qdrant sidecar, no cloud accounts.

Five MCP tools -- store, recall, forget, reflect, stats -- give agents persistent memory across conversations. Memories are typed (episodic events, semantic facts, procedural workflows), entities get resolved even when agents name them inconsistently, and facts carry temporal validity so stale stuff ages out instead of silently misleading.

Usage

Add to ~/.claude/settings.json:

With uvx:

{
  "mcpServers": {
    "ferrex": {
      "command": "uvx",
      "args": ["ferrex"]
    }
  }
}

With ferrex on PATH (via Nix, cargo install, or release binary):

{
  "mcpServers": {
    "ferrex": {
      "command": "ferrex"
    }
  }
}

nix run github:vaporif/ferrex

cargo install --path crates/server

Architecture

flowchart TD
    Agent -->|MCP stdio| Server["ferrex"]
    Server --> Core["ferrex-core"]

    subgraph store_flow["store"]
        Core -->|1| Validate["validate\n<i>field limits, type detect</i>"]
        Validate -->|2| NormPred["normalize predicate\n<i>synonym groups</i>"]
        NormPred -->|3| Embed["ferrex-embed\n<i>fastembed ONNX</i>"]
        Embed -->|4| Dedup["dedup check\n<i>cosine >= 0.95 → reject</i>"]
        Dedup -->|5| Conflict["conflict resolution\n<i>semantic triples only</i>"]
        Conflict -->|6| Resolve["entity resolution\n<i>exact → fuzzy → embedding</i>"]
        Resolve -->|7a| SQLite["SQLite\n<i>metadata, entities,\ntemporal validity</i>"]
        Resolve -->|7b| Qdrant["Qdrant\n<i>dense + sparse vectors</i>"]
    end

    subgraph recall_flow["recall"]
        Core -->|1| EmbedQ["embed query\n<i>+ cache lookup</i>"]
        EmbedQ -->|2| Hybrid["hybrid search\n<i>dense + BM25, RRF fusion</i>"]
        Hybrid -->|3| Rerank["rerank\n<i>BGE cross-encoder</i>"]
        Rerank -->|4| Boost["recency boost\n<i>type-specific half-life</i>"]
        Boost -->|5| Stale["staleness scoring\n<i>age + access + validation</i>"]
        Stale -->|6| Return["results → agent"]
    end

    Hybrid --> Qdrant
    Stale --> SQLite

Four crates:

MCP tools

store

Save a memory. Type auto-detects from fields (subject+predicate+object = semantic, content = episodic), or set it yourself.

Pipeline: validate → normalize predicate → embed → dedup check → conflict resolution → entity resolution → dual write → journal

recall

Semantic search with hybrid retrieval and reranking.

Pipeline: embed query → hybrid search (dense + BM25 sparse, RRF fusion) → rerank (BGE cross-encoder) → recency boost → staleness scoring → filter and return

forget

Delete memories by ID from both stores.

reflect

Audit memory health. Finds stale memories and contradicting semantic facts.

stats

Memory system overview.

Memory types

Semantic memories have t_valid/t_invalid timestamps. When a new fact supersedes an old one, the old memory gets invalidated rather than deleted, so you keep the history.

How things work

Entity resolution

Agents are bad at consistent naming ("tokio" vs "Tokio" vs "tokio runtime"). ferrex resolves entities in stages:

1. Normalize (lowercase, trim, collapse separators)
2. Exact match against the aliases table
3. Fuzzy match -- Jaro-Winkler > 0.85, matched name stored as alias
4. Embedding match -- cosine > 0.92, stored as alias
5. Nothing matched -- new entity created

Predicate normalization

Free-form predicates get mapped to canonical groups. "uses", "depends-on", "requires", and "imports" all resolve to depends_on. Groups are configurable per namespace in ferrex.toml.

Conflict resolution (semantic)

When you store a triple with the same subject and normalized predicate as something already in the system:

• Object similarity >= 0.95: duplicate, rejected
• Object similarity < 0.50: update, old memory invalidated
• 0.50--0.95: ambiguous, you need to pass supersedes explicitly

Deduplication (episodic/procedural)

New memories get embedded and compared against existing ones in the same namespace. Cosine similarity >= 0.95 (configurable) triggers rejection.

Staleness scoring

Recalled memories get a staleness score between 0.0 (fresh) and 1.0 (stale):

score = 0.40 * age_decay + 0.25 * access_decay + 0.25 * validation_decay + 0.10 * count_freshness

Decay is exponential with half-lives tuned per memory type. Results come back labeled fresh, aging, or stale based on configurable thresholds.

Hybrid retrieval and reranking

Recall runs both dense (cosine) and sparse (BM25) searches in Qdrant, fuses them with reciprocal rank fusion, then reranks the top candidates using a BGE cross-encoder. Recency boosts are type-specific: episodic memories get a stronger recent-is-better signal than semantic ones, procedural gets none.

Configuration

CLI flags, environment variables, or ~/.ferrex/ferrex.toml.

Embedding models

TOML config

Thresholds, predicate synonym groups, staleness weights, cache sizes -- all configurable in ferrex.toml. See docs/design/ferrex-rag-memory.md for the full schema.

CLI commands

ferrex                              # start MCP server (default)
ferrex audit reconcile [--fix]      # detect/fix Qdrant<>SQLite mismatches
ferrex backfill normalized-predicates [--dry-run]  # populate missing normalized predicates

Design docs

• Main design doc -- architecture, memory types, MCP tool API, retrieval pipeline
• Design decisions -- 24 numbered decisions with rationale
• References -- papers, benchmarks, prior art
• Roadmap -- phased implementation plan
• Future improvements -- v2 features, deferred until there's measurement data

License

MIT