Architecture · 0.15 · Developer Preview
How Ferrosa Memory works.
A thin memory layer over a real database — typed graph, bi-temporal facts, hybrid retrieval, background consolidation, and auditable forgetting — all reachable through MCP tools.
A thin memory layer over a real database — typed graph, bi-temporal facts, hybrid retrieval, background consolidation, and auditable forgetting — all reachable through MCP tools.
An agent never talks to storage directly. It calls MCP tools; Ferrosa Memory owns the semantics of memory; and Ferrosa DB provides durable, indexed substrate underneath. Each layer has a single job, so the layer above can stay simple.
At the top, an agent, IDE, or runtime issues a small, stable set of MCP calls — ingest, retrieve, link, explain, forget. It does not know how a fact is stored, indexed, or ranked; it only knows the tool contract.
The memory service translates those calls into memory semantics: entities and typed edges, bi-temporal facts, trajectory folds, context segments, intentions, and the forget journal. This is where dedup, supersession, ranking, and consolidation policy live.
Underneath, Ferrosa DB does the heavy lifting: CQL storage for the wide-column tables, HNSW vector indexes for semantic recall, a property graph for traversal, and S3-backed durability with hot/warm/cold tiering so memory survives restarts and scales past a single process.
Agent / IDE / runtime
│ MCP tools (ingest · retrieve · link · explain · forget)
▼
Ferrosa Memory service ← owns memory *semantics*
├─ entities + typed graph
├─ bi-temporal facts (supersession)
├─ trajectory folds + context segments
├─ hybrid retrieval (Reciprocal Rank Fusion)
├─ dream-cycle consolidation
└─ auditable forget journal
│
▼
Ferrosa Database ← durable, indexed substrate
CQL storage · HNSW vectors · property graph · S3 hot/warm/cold tieringA vector store gives you one shape: a blob with an embedding. Ferrosa Memory gives you the shapes agents actually reason over — and stores each one natively so it can be queried, linked, and explained.
Named entities are deduplicated with phonetic matching (Double Metaphone) and connected by typed edges — depends_on, contains, calls, uses, references, related_to — alongside legacy bidirectional links like CO_OCCURS_WITH and SUPERSEDES. An agent can follow relationships, not just match strings.
Facts are timestamped and superseded rather than overwritten. Retrieval returns the most-recent-valid value by default, while the full supersession chain stays inspectable — so you can audit what was known, and when, and time-travel back through it.
A content-hash-keyed cache of completed sub-call results. When a deterministic sub-task recurs, the prior result is returned from cache instead of paying for a redundant LLM call — memory that saves work, not just stores it.
Hierarchical, depth-nested plan and task nodes capture how a complex job decomposes. When a sub-task returns, parent context is re-injected, so a deep agent keeps its place instead of losing the thread.
Open a fold for a sub-task, append turns as work proceeds, then seal it with a summary and an embedding (a FOLDED_INTO edge). Long trajectories compress into recallable units without throwing away the detail underneath.
Documents are stored as a hierarchy — document → section → chunk — with semantic previous/next links. When a search hits one chunk, get_chunk_context expands around it to recover the surrounding evidence a single hit would miss.
Raw conversation turns are persisted as deterministic semantic segments, dual-indexed for both lexical (BM25) and vector recall, with temporal previous/next links for bounded expansion windows. The transcript becomes searchable structure.
No single signal is enough — vectors miss exact strings, keywords miss paraphrase, and neither knows what matters in this workspace. Ferrosa Memory runs many retrievers and combines them with Reciprocal Rank Fusion, so a result that several independent signals agree on rises to the top.
Optional query decomposition expands a request into lexical and LLM-generated variants before retrieval. Reciprocal Rank Fusion merges every signal's ranking into one list. Workspace-aware reranking then boosts or demotes results by the current working directory, so local context wins. An optional LLM judge / reranker can take a final pass — but it is off by default.
Relevance feedback on a result set is recorded and folded back into the feedback reputation signal, so future rankings reflect what actually helped. Recall is treated as a system that improves with use — not a fixed similarity threshold frozen at index time.
Human memory consolidates during rest. Ferrosa Memory does the same: a background "dream cycle" runs during idle periods — and after enough new ingests — turning a pile of fresh facts into linked, ranked, durable knowledge. You can also force a pass with run_consolidation at wrap-up.
Newly ingested memories are sorted and prepared for deeper processing, separating signal worth linking from noise that can rest.
Within-fold and pairwise analysis surfaces relationships between memories that arrived separately, proposing new edges across the graph.
Clusters of co-occurring entities are summarized into higher-level insights, so recurring patterns become first-class, retrievable memory.
Graph centrality is recomputed as the structure grows, keeping the authority signal that feeds retrieval current with the latest links.
An Ebbinghaus-style forgetting curve cools memory that hasn't been touched, so stale context fades in ranking instead of crowding fresh recall.
High-confidence derived predicates are materialized for fast reuse, so repeatedly inferred facts don't have to be recomputed on every query.
Deleting a memory in a connected graph is dangerous — it can orphan edges, break temporal chains, and invalidate derived facts. So forget is two-phase: look before you leap, then leap with a receipt.
A hybrid search finds forget candidates and computes their blast radius: direct edges, temporal supersession chains, derived facts that reference the entity, and inbound references. Nothing is mutated. The phase returns a signed, TTL'd token describing exactly what would change.
Confirmation replays the token under a TOCTOU guard: a content_hash check rejects the operation if the underlying memory changed since the proposal, so you never delete something other than what you reviewed. The change is recorded in an append-only ForgetJournal before any state is touched.
The default mode is a reversible retraction — a soft-delete to state=unavailable that hides the memory from recall but keeps it restorable via restore_forgotten. When you genuinely need it gone, a hard delete performs a graph DETACH DELETE. Both are journaled.
Because every forget is journaled before it executes, a crash mid-operation can't leave memory half-deleted. A startup recovery sweep reprocesses incomplete forgets to a clean state — the append-only journal is the source of truth.
The best memory layer is one an agent doesn't have to think about. Ferrosa Memory wires into the session lifecycle through hooks, so recall and capture happen automatically, scoped to the workspace, and biased toward silence over noise.
When a session begins, a hook automatically runs check_intentions and a hybrid search for the current context — so the agent opens with what it already knows, before it reads a single file.
A turn-capture hook persists conversation turns into context segments and queues consolidation, so today's work becomes tomorrow's recallable memory without an explicit save step.
0.15 derives stable, per-workspace hook sessions instead of leaning on process-global state — and fallback recall stays semantic and procedural, never a raw episodic transcript leaking across sessions.
Recall-relevance guards, lexical-overlap checks, and workspace filtering mean a hook would rather surface nothing than inject low-confidence context. Quiet recall keeps the agent's window clean.
set_intention defers an action to fire later on a Topic, FilePattern, Duration, or Context trigger; check_intentions fires the matching ones at session start. Memory remembers not just the past, but what to do next.
A focus stack, working set, and recovery hints survive restarts and support multi-agent handoff — so an interrupted agent can pick up exactly where the last one left off.
The architecture is the why. The tool catalog is the how — and the comparison shows what structured memory buys you over a vector store.