Memory V3

memory-v3

Brain-inspired persistent memory for AI coding assistants

---

Why memory-v3?

pip install memory-v3-hx

| Feature | mem0 | Zep | LangMem | memory-v2 | memory-v3 | |---|---|---|---|---|---| | Persistent local storage | -- | Cloud | Cloud | SQLite | SQLite + WAL | | Vector search | Qdrant/Pinecone | Postgres | Pinecone | sqlite-vec | sqlite-vec + FTS5 + community routing | | Knowledge graph | -- | -- | -- | Single NetworkX | 4-layer MAGMA (semantic/temporal/causal/entity) | | Retrieval pipeline | Vector only | Vector + keyword | Vector | Hybrid (BM25 + vec) | 3-stage (coarse -> fine -> organize) | | Cognitive scoring | -- | -- | -- | ACT-R + FadeMem | ACT-R + FadeMem + surprise + fan effect | | Governance hierarchy | -- | -- | -- | Protected flag | 4-tier constitutional (decay/archive per layer) | | Source verification | -- | -- | -- | -- | HaluMem (SHA-256 source-hash check + confidence decay) | | Memory consolidation | -- | -- | -- | -- | 4-phase sleep (replay/reorganize/compress/prune) | | Intake filtering | -- | -- | Partial | Dedup only | 6-gate sensory filter | | Self-linking | -- | -- | -- | -- | Zettelkasten (auto bidirectional, cosine > 0.5) | | Surprise scoring | -- | -- | -- | -- | Titans-inspired (centroid distance) | | Structure awareness | -- | -- | -- | -- | 4 types (timeline/ledger/taxonomy/narrative) | | Fan effect | -- | -- | -- | -- | ACT-R IDF penalty | | Multi-agent sync | -- | Partial | -- | Changelog | Changelog + conflict resolution | | Async writes | -- | -- | -- | -- | Priority queue (1-5, batch flush) | | MCP tools | -- | -- | -- | 17 | 24 | | Embedding model | OpenAI | OpenAI | OpenAI | Local (Ollama) | Local (Ollama, 768-dim nomic-embed-text) | | LLM for extraction | External API | External API | External API | Local (Ollama) | Local (Ollama, qwen2.5:3b) | | Privacy | -- | -- | -- | Full local | Full local (zero cloud dependency) |

---

Abstract

memory-v3 is a next-generation persistent memory system for AI coding assistants, implemented as a Model Context Protocol (MCP) server exposing 24 tools across CRUD, search, graph traversal, lifecycle management, and system operations. It stores memories in a SQLite database augmented with sqlite-vec for 768-dimensional vector search and FTS5 for keyword retrieval, backed by four independent NetworkX directed graphs (semantic, temporal, causal, entity) that together form the Multi-Agent Graph Memory Architecture (MAGMA). Retrieval follows a 3-stage pipeline: coarse candidate filtering via community routing, vector search, and FTS5 (capped at 500 candidates); fine-grained scoring via Reciprocal Rank Fusion, ACT-R cognitive activation with fan effect penalties, HaluMem confidence adjustment, and Titans-inspired surprise weighting; and post-retrieval organization using graph neighbor expansion, structure-type detection, and zettelkasten see-also linking. A 4-tier constitutional governance hierarchy (Constitutional, Legislative, Factual, Ephemeral) assigns per-layer decay rates, activation floors, and archival policies, ensuring that identity-critical memories never decay while ephemeral episodes are aggressively reclaimed. The system runs entirely locally via Ollama for both embeddings (nomic-embed-text) and LLM extraction (qwen2.5:3b), requiring zero cloud API keys, and totals approximately 10,565 lines of Python across 40 modules.

---

Table of Contents

• [Architecture Overview](#architecture-overview)
• [Theoretical Foundations](#theoretical-foundations)
• [ACT-R Cognitive Scoring](#act-r-cognitive-scoring)
• [FadeMem with Surprise](#fademem-with-surprise)
• [Reciprocal Rank Fusion](#reciprocal-rank-fusion)
• [Unified Scoring Formula](#unified-scoring-formula)
• [Fan Effect Penalty](#fan-effect-penalty)
• [Surprise Scoring](#surprise-scoring)
• [Governance Hierarchy](#governance-hierarchy)
• [3-Stage Retrieval Pipeline](#3-stage-retrieval-pipeline)
• [Multi-Graph Architecture (MAGMA)](#multi-graph-architecture-magma)
• [Database Schema](#database-schema)
• [MCP Server and Tools](#mcp-server-and-tools)
• [Subsystem Reference](#subsystem-reference)
• [Worked Examples](#worked-examples)
• [Installation](#installation)
• [Configuration](#configuration)
• [Usage](#usage)
• [Repository Structure](#repository-structure)
• [Lineage](#lineage)
• [Related Work](#related-work)
• [References](#references)

---

Architecture Overview

                          +---------------------+
                          |    MCP Client        |
                          | (Claude Code, etc.)  |
                          +----------+----------+
                                     |
                                     | FastMCP (stdio/SSE)
                                     v
                     +-------------------------------+
                     |        server.py               |
                     |    24 MCP Tool Endpoints       |
                     +------+-------+-------+--------+
                            |       |       |
              +-------------+   +---+---+   +-------------+
              |                 |       |                   |
              v                 v       v                   v
    +------------------+  +---------+ +----------+  +---------------+
    |   Sensory Gate   |  |  CRUD   | |  Search  |  |   Lifecycle   |
    | (6-gate filter)  |  | (db.py) | | Pipeline |  |   Manager     |
    +--------+---------+  +----+----+ +----+-----+  +-------+-------+
             |                 |            |                |
             v                 v            v                v
    +------------------+  +--------+  +-----------+  +---------------+
    | credential scan  |  | SQLite |  | 3-Stage   |  | extraction    |
    | exact dedup      |  | + vec0 |  | Retrieval |  | consolidation |
    | near dedup       |  | + FTS5 |  |           |  | compaction    |
    | surprise score   |  | + WAL  |  | Stage 1:  |  | verification  |
    | topic cluster    |  +---+----+  |  Coarse   |  | decay sweep   |
    | length check     |      |       | Stage 2:  |  +---------------+
    +------------------+      |       |  Fine     |
                              |       | Stage 3:  |
                              |       |  Organize |
                              |       +-----------+
                              |
              +---------------+----------------+
              |               |                |
              v               v                v
    +------------------+ +---------+  +----------------+
    |  Scoring Engine  | |  Async  |  | MAGMA Graphs   |
    |                  | |  Write  |  |                |
    | ACT-R activation | |  Queue  |  | semantic.pkl   |
    | FadeMem decay    | | (1-5    |  | temporal.pkl   |
    | surprise score   | | priority|  | causal.pkl     |
    | fan effect       | | levels) |  | entity.pkl     |
    | hierarchy rules  | +---------+  |                |
    +------------------+              | Leiden detect  |
                                      | PPR traversal  |
                                      | Zettelkasten   |
                                      +----------------+

---

Theoretical Foundations

ACT-R Cognitive Scoring

memory-v3 implements the Adaptive Control of Thought -- Rational (ACT-R) framework (Anderson & Lebiere, 1998) for computing memory activation levels. Higher activation means a memory is more likely to be needed in the current context.

Base-level activation reflects how frequently and recently a memory has been accessed:

B_i = ln(n / (1 - d)) - d * ln(L)

Where:

• n = access count (number of times the memory has been retrieved)
• d = decay parameter (default 0.5)
• L = lifetime in hours since memory creation

Spreading activation models contextual priming from shared tags:

S_i = SUM over shared tags j of: W_j * (S_max - ln(fan_j))

Where:

• W_j = 1 / |context_tags| (source activation distributed evenly)
• S_max = maximum associative strength (default 1.6)
• fan_j = number of memories associated with tag j

Activation noise adds stochastic variability via a logistic distribution:

epsilon ~ Logistic(0, s)

Sampled as: epsilon = s * ln(u / (1 - u))
    where u ~ Uniform(0, 1)

The logistic distribution has variance (pi * s)^2 / 3, with s = 0.25 by default.

Full activation combines all components with a governance-aware floor:

A_i = max(B_i + S_i + epsilon, activation_floor)

Where activation_floor depends on the governance layer:

• Layer 1 (Constitutional): floor = 5.0
• Layer 2 (Legislative): floor = 2.0
• Layer 3 (Factual): floor = -0.5
• Layer 4 (Ephemeral): floor = -2.0

Protected memories receive an activation floor of at least 0.0.

Retrieval probability uses the sigmoidal (softmax) rule:

P_i = 1 / (1 + exp(-(A_i - tau) / s))

Where:

• tau = retrieval threshold (default -0.5)
• s = noise scale (default 0.25)

FadeMem with Surprise

FadeMem manages memory lifecycle through a 4-weight importance function that balances relevance, frequency, recency, and novelty. The v3 extension adds a surprise component inspired by Titans (Google, 2024).

Importance score:

I(t) = alpha * relevance + beta * frequency + gamma * recency + delta * surprise

With default weights:

• alpha = 0.30 (relevance -- semantic similarity to active context)
• beta = 0.25 (frequency -- log-normalized access count)
• gamma = 0.25 (recency -- exponential decay from last access)
• delta = 0.20 (surprise -- Titans-inspired novelty signal)

Frequency is log-normalized against the corpus maximum:

frequency = ln(access_count + 1) / ln(max_access_count + 1)

Recency uses exponential decay with a layer-aware rate:

recency = exp(-lambda * t)

Where lambda is the governance layer's decay rate and t is hours since last access.

Weibull-style strength decay for long-term value tracking:

v(t) = v(0) * exp(-lambda * t^beta)

Where beta 1 produces slow-then-fast.

Memory layer classification based on importance:

importance >= 0.7  -->  LTM (long-term memory)
importance >= 0.3  -->  STM (short-term memory)
importance   current (candidate for archive)

Reciprocal Rank Fusion

Stage 2 fuses BM25 keyword rankings and vector similarity rankings using RRF (Cormack et al., 2009):

RRF(d) = 1 / (k + rank_bm25(d)) + 1 / (k + rank_vec(d))

Where:

• k = 60 (smoothing constant, configurable via MEMORY_V3_RRF_K)
• rank_bm25(d) = 0-based position in FTS5 results (9999 if absent)
• rank_vec(d) = 0-based position in vector results (9999 if absent)

RRF is robust to score-scale mismatch between BM25 and cosine distance, requiring no normalization.

Unified Scoring Formula

The final retrieval score combines search relevance, cognitive activation, and verification confidence:

final = 0.60 * hybrid_score + 0.25 * (A / 10.0) + 0.15 * confidence

Where:

• hybrid_score = RRF fusion score from BM25 + vector search
• A = full ACT-R activation (base-level + spreading + noise, floored)
• confidence = HaluMem-adjusted confidence (verification-aware)

HaluMem confidence adjustment:

• verified status: confidence unchanged
• stale status (> 90 days unverified): confidence *= 0.7
• contradicted status: confidence *= 0.3

The 60/25/15 weighting ensures search relevance dominates while cognitive signals and verification status provide meaningful re-ranking.

Fan Effect Penalty

The fan effect (Anderson, 1974) models the cognitive finding that as a concept becomes associated with more facts, each individual association becomes harder to retrieve. memory-v3 adds a logarithmic penalty to spreading activation:

fan_penalty(n) = delta * ln(n + 1)

Where delta = 0.3 (configurable via MEMORY_V3_FAN_DELTA).

Spreading activation with fan penalty:

S_i = SUM over shared tags j of:
    W_j * max(S_max - ln(fan_j) - fan_penalty(total_connections_j), 0)

The per-tag contribution is floored at zero to prevent negative activation. This is the ACT-R equivalent of IDF weighting: tags shared across many memories contribute less spreading activation than rare, specific tags.

Surprise Scoring

Surprise quantifies how unexpected a new memory is relative to the existing knowledge base. Inspired by the Titans architecture (Google DeepMind, 2024), surprise biases the system toward retaining novel information.

Centroid-based surprise:

surprise = 1.0 - max(cosine_similarity(embedding, c_i) for c_i in centroids)

Where centroids are the mean embeddings of each topic cluster, stored in the cluster_centroids table and recomputed during consolidation.

• surprise = 0.0 means the memory is identical to a known cluster center
• surprise = 1.0 means the memory is maximally dissimilar to all clusters
• surprise = 0.5 is the neutral default when no centroids exist

Cluster assignment maps each memory to its nearest centroid:

cluster(m) = argmin_i (1 - cosine_similarity(embedding_m, c_i))

Centroids are L2-normalized after recomputation for consistent cosine comparisons.

Governance Hierarchy

The Constitutional Governance Hierarchy assigns every memory to one of four tiers that control its decay behavior, activation floor, and archival eligibility:

| Layer | Name | Decay Rate | Activation Floor | FadeMem Beta | Archivable | Archive After | Example Types | |---|---|---|---|---|---|---|---| | 1 | Constitutional | 0.0 | 5.0 | N/A | Never | N/A | identity, chainofcommand | | 2 | Legislative | 0.01 | 2.0 | 0.5 | Never | N/A | decision, correction, commitment | | 3 | Factual | 0.10 | -0.5 | 0.8 | Yes | 30 days, I Layer 1; decision/correction/commitment/exact_value tags -> Layer 2)

1. Content type mapping (content_type string to layer)
2. Protected flag bump (protected memories get at least Layer 2)
3. Default to Layer 3 (Factual)

Archival rules:

should_archive(m) =
    NOT (tags INTERSECT protected_tags) AND
    layer.can_archive AND
    importance  layer.min_archive_age_days

Protected tags that always prevent archival: correction, decision, identity, emotional_anchor, commitment, exact_value, chain_of_command, person.

---

3-Stage Retrieval Pipeline

Stage 1: Coarse Candidate Filtering

Fast, broad retrieval to build a candidate pool. Three channels run in parallel:

1. Community routing -- Find top-N communities by centroid similarity

to the query embedding, then collect all memory IDs in those communities. Default N = 3 (configurable via MEMORY_V3_STAGE1_COMMUNITY_TOP).

1. Vector search -- Fast approximate nearest neighbor via the memory_vec

virtual table (vec0), returning up to 200 candidates ordered by distance.

1. FTS5 keyword search -- Full-text search with per-word quoting for

safe special character handling, returning up to 200 candidates by rank.

The three channels are unioned with ordered deduplication (vector results first, then FTS, then community), capped at stage1_max_candidates (default 500).

Stage 2: Fine-Grained Scoring

Each candidate from Stage 1 receives a composite score:

1. Re-rank via RRF -- BM25 and vector rank positions are fused:

rrf = 1/(k + bm25_rank) + 1/(k + vec_rank)

1. ACT-R activation -- Base-level + spreading (with fan penalty) + noise,

floored by g

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Haustorium12
• Source: Haustorium12/memory-v3
• License: MIT

Install and usage instructions live in the source repository linked above.