Architecture
Pensyve is a Rust-native memory runtime designed to give AI agents human-like memory. Instead of stuffing everything into a prompt, agents store experiences, extract knowledge, and retrieve relevant memories on demand — with the right ones surfacing at the right time.
Memory Types
Every memory in Pensyve is classified into one of three types, inspired by cognitive psychology:
| Type | What it captures | Example |
|---|---|---|
| Episodic | Specific experiences — what happened, when, with whom | "Alice asked about project X on March 15" |
| Semantic | Factual knowledge — subject-predicate-object triples | "Alice prefers dark mode" |
| Procedural | Action-outcome patterns with Bayesian reliability tracking | "Running cargo test after refactoring catches regressions 94% of the time" |
Episodic memories are extracted automatically from conversation episodes. Semantic memories come from explicit remember() calls or LLM extraction. Procedural memories are built from repeated action-outcome observations.
8-Signal Retrieval
When you call recall(), Pensyve doesn't just do a vector search. It evaluates every candidate memory across eight independent signals, then fuses them using Reciprocal Rank Fusion (RRF) to produce a final ranking.
The Signals
| # | Signal | Source | What it measures |
|---|---|---|---|
| 1 | Vector similarity | HNSW index (GTE-Small, 384d) | Semantic relevance — how close the query is to the memory in embedding space |
| 2 | BM25 | SQLite FTS5 | Lexical relevance — exact keyword and phrase matching |
| 3 | ACT-R activation | Access history | Recency × frequency — memories accessed recently and often score higher (Anderson 2007) |
| 4 | Spreading activation | Knowledge graph (petgraph) | Graph proximity — memories connected to the query entity via temporal, causal, or semantic edges |
| 5 | Query intent | Keyword classifier | Intent alignment — procedural memories rank higher for "how do I" queries, episodic for "what happened" queries |
| 6 | Confidence | Memory metadata | Source reliability — semantic confidence, procedural reliability scores |
| 7 | PMI surprise | Access statistics | Unexpectedness — memories that are rarely accessed but highly relevant get a surprise boost (arXiv:2508.17403) |
| 8 | Cross-encoder reranking | BGE Reranker Base | Deep relevance — a cross-encoder rescores the top 20 candidates for fine-grained ranking |
Fusion
Individual signals produce ranked lists. These are combined via weighted Reciprocal Rank Fusion (Cormack et al., SIGIR 2009):
RRF_score(d) = Σ_r w_r / (k + rank_r(d))The smoothing constant k is adaptive — it scales with the candidate pool size rather than using a fixed value, preserving rank discrimination in small corpora.
Rankings with no discriminative signal (all scores identical) are automatically dropped to avoid diluting strong signals.
Default weights: [1.0, 0.8, 1.0, 0.8, 0.5, 0.5] for vector, BM25, activation, spread, intent, and confidence.
FSRS Decay
Memories don't live forever. Pensyve uses the Free Spaced Repetition Scheduler (FSRS) to model memory decay — the same algorithm used by Anki.
Forgetting Curve
R(t, S) = (1 + t / (9 × S))^(-1)- At
t = 0: retrievability = 1.0 (just accessed) - At
t = S: retrievability ≈ 0.9 (one stability interval) - At
t = 9S: retrievability = 0.5 (half-life)
Reinforcement
When a memory is successfully recalled, its stability increases:
S_new = S × (1 + 0.5 × (11 - D) × S^(-0.2) × (e^(0.2 × (1-R)) - 1))Harder memories (higher difficulty) and memories with lower retrievability at recall time get a bigger stability boost — the "desirable difficulty" effect.
Salience Modulation
Not all memories decay at the same rate. Pensyve computes a salience score from four factors:
- Novelty (40%) — how different the memory is from existing knowledge
- Importance (30%) — entity-level significance markers
- Extremity (10%) — outlier detection in the embedding space
- Specificity (20%) — information density of the content
High-salience memories get a stability boost: S_effective = S × (1 + β × salience), making important memories decay slower.
Consolidation
Periodic consolidation promotes, decays, and archives:
- Promote: Episodic memories that appear ≥3 times become semantic facts
- Decay: Apply FSRS retrievability to all memories
- Archive: Memories below the stability threshold are soft-deleted
Knowledge Graph
Pensyve maintains a directed graph (via petgraph) connecting entities and memories through typed edges:
| Edge Type | Meaning | Example |
|---|---|---|
Temporal | Happened before/after | Episode A → Episode B |
Causal | Caused, led to | "Refactoring → test failures" |
Entity | About, mentions, involves | Memory → Alice |
Semantic | Similar to, related to | Fact A ↔ Fact B |
Supersedes | Replaces, updates | New preference → old preference |
Graph edges carry temporal confidence that decays exponentially: confidence(t) = base × e^(-age × ln(2) / half_life). Stale relationships naturally lose influence.
During recall, BFS traversal from the query entity discovers connected memories. Edge type alignment with query intent produces the spreading activation signal fed into RRF.
Storage
Pensyve is offline-first. The default storage backend is SQLite — zero configuration, no external services, works everywhere.
For managed deployments (Pensyve Cloud), a Postgres backend is feature-gated, enabling multi-tenant isolation and horizontal scaling.
Both backends implement the same StorageTrait, so the retrieval engine is storage-agnostic.
All ONNX models (GTE-Small, BGE Reranker, Florence-2, UniXcoder) run locally via the ort crate — no external API calls for embedding or reranking.