Ferrosa Memory is durable working memory for AI agents. It turns one-off agent
sessions into a long-running, searchable knowledge system: plans survive restarts,
important facts keep their history, documents become retrievable by meaning, and
future sessions can pick up work without rebuilding the same context from scratch.
Ferrosa Memory is an MCP-native memory server. Typed facts with history, plans, skills, graph relationships and folded context — returned by meaning, keyword, sound, or graph traversal. Forgetting is auditable and reversible.
Estrelas
7
Ferramentas
—
Disponibilidade
—
It runs as an MCP server backed by Ferrosa DB.
Agents call normal MCP tools; Ferrosa Memory handles storage, retrieval,
consolidation, and governance behind those tools.
Community and support
Join the Ferrosa Discord to discuss deployments,
ask questions, and report issues with the community and maintainers.
Why it exists
Most agent workflows still behave like disposable chat windows. When the process
ends, the useful context disappears with it:
subagents recompute work that already happened;
plans and decisions get buried in transcripts;
entities discovered in one session are invisible to the next;
retrieval returns loose fragments instead of the surrounding project frame;
stale deadlines and superseded facts keep polluting prompts.
Ferrosa Memory fixes that by giving agents a typed memory plane instead of a pile
of logs. It stores facts, plans, folds, documents, graph edges, skills, feedback,
and future constraints as first-class records that can be searched, explained,
aged out, superseded, or deleted.
What it gives agents
Context that survives restarts — restore the active workspace, branch,
entities, plan state, and recent decisions at session start.
Less repeated work — memoize sub-call results by content hash and reuse
previously computed answers.
Long-running plans — keep hierarchical plan nodes in storage and retrieve
only the relevant path when work resumes.
Entity-aware recall — track people, projects, files, concepts, and links
with phonetic deduplication and graph traversal.
Temporal memory — store timestamped facts with supersession so “latest
valid answer” beats stale context.
Time-bounded foresight — represent future constraints with
valid_from/valid_until, then automatically stop surfacing them after they
expire.
Document recall — ingest documents as document, section, and chunk records
with BM25, vector, phonetic, and graph-based candidate generation.
Consolidated scenes — background consolidation folds clusters of related
entities into coherent retrievable scenes, then expands them back to member
entities during recall.
Retrieval feedback — record traces, abstentions, judge results, and user
feedback for offline tuning and regression detection.
Modern MCP draft support — shared HTTP clients can discover capabilities,
read task resources, and subscribe to workspace task updates with the
2026-07-28 per-request protocol.
Operational controls — tenant isolation, audit trails, reversible
forgetting, rule governance, and fail-loud health checks.
How it works
Ferrosa Memory is a thin product layer over Ferrosa's public data interfaces. MCP
clients talk to Ferrosa Memory; Ferrosa Memory decides which memory tool is being
used, authenticates the request, writes app-owned memory records through CQL,
and uses Ferrosa graph/query interfaces for graph-owned data.
%%{init: {'theme':'dark','themeVariables':{'primaryColor':'#16161f','primaryTextColor':'#e8e8ed','primaryBorderColor':'#e2725b','lineColor':'#9494a3','secondaryColor':'#1c1c28','tertiaryColor':'#111118','clusterBkg':'#111118','clusterBorder':'#1e1e2a','edgeLabelBackground':'#111118','nodeTextColor':'#e8e8ed'}}}%%
graph TD
subgraph Clients
CC[Claude Code]
CA[Claude.ai]
TP[Third-party MCP clients]
WB[Workbench]
end
subgraph MCP["Ferrosa Memory MCP server"]
TR[Tool router]
AT[Auth and tenant scope]
MEM[Memory tools]
DAT[Datalog engine]
CU[Compression and upkeep]
end
subgraph DB["Ferrosa DB"]
APP[App-owned memory tables]
IDX["BM25 · Vector · Phonetic · B-tree"]
GRAPH["Graph interfaces"]
ST["NVMe → S3 → Glacier"]
end
CC -->|stdio| TR
CA -->|HTTP+SSE| TR
TP -->|HTTP+SSE| TR
WB -->|CQL / SPARQL / Datalog surfaces| TR
TR --> AT
AT --> MEM
MEM -->|direct CQL for memory records| APP
MEM -->|graph reads/writes| GRAPH
DAT -->|local inference over memory data| MEM
CU -->|compression and background consolidation| MEM
APP --- IDX
GRAPH --- IDX
APP --- ST
GRAPH --- ST
The key boundary is ownership, not syntax. Direct CQL is correct for tables owned
by Ferrosa Memory, such as entities, folds, context segments, temporal facts,
feedback, configuration, and retrieval traces. Graph-owned backing tables are not
a public API; graph reads and writes go through graph interfaces.
Surface
Contract
App-owned memory tables
Direct CQL is allowed. Ferrosa Memory owns the schema and migrations.
Graph reads and writes
Use graph interfaces, not direct mutation of graph backing tables such as typed_edges, folded_into, mentioned_in, co_occurs_with, or supersedes.
Workbench CQL
Authenticated pass-through to Ferrosa's public CQL contract. Fail loud if Ferrosa rejects the query.
Workbench SPARQL
Authenticated pass-through to Ferrosa's public SPARQL contract. Fail loud if Ferrosa rejects the query.
Workbench Datalog
Local Ferrosa Memory inference over Ferrosa-backed graph and app data. It is not a Ferrosa wire-protocol contract.
That keeps the product honest: Ferrosa Memory uses Ferrosa instead of cloning
Ferrosa behavior locally. If a public Ferrosa interface cannot express a needed
operation, the fix belongs in Ferrosa's public graph/query surface rather than in
a private backing-table workaround.
Tools
The current snapshot contains 95 MCP tool definitions. The default
tools/list remains a smaller tier for agent token economy. Catalog discovery
is paginated at complete tool boundaries and every caller-visible result is
capped at 16,384 UTF-8 bytes. include_all: true remains a paginated
compatibility mode.
all_tools keeps its public name and defaults to compact entries. Search in
place with {"query":"graph"}, filter with {"categories":["graph"]}, or
fetch a full schema with {"names":["search"]}. When has_more is true, send
the returned hint.next_arguments unchanged; it includes the opaque,
catalog-versioned cursor. Final pages include a named-schema lookup hint, and a
stale cursor returns current version plus safe restart arguments. See the
tool catalog architecture.
Candidate-confirmed forgetting: propose candidates (with blast radius) → confirm to retract (reversible, audited, restorable) or hard-delete; restore_forgotten reverses a retraction
MCP draft support
Shared HTTP deployments support the MCP draft per-request protocol version 2026-07-28 for modern clients. The supported surface includes server/discover, tools, prompts, task resources, and task-resource subscriptions over Server-Sent Events.
Use this when a client wants to discover capabilities without a legacy initialize session, read active task resources directly, or subscribe to workspace task updates for multi-agent coordination. See the protocol guide, compatibility matrix, and demo runbook for the implemented claim boundary and reproducible evidence.
Entity Scope Defaults
list_entities, get_stats (and its stats alias), and
count_entities_by_type are tenant-wide by default. Supply both
scope: "session" and session_id to scope a read to one session.
Passing session_id alone does not change the read scope.
Recall quality
Beyond raw storage, ferrosa-memory actively improves what comes back from a search. Most
of this is automatic — a background dream cycle runs on a periodic tick (default every
~20 s when there is new data) and builds the structures below for free. See
docs/recall-quality.md for the full guide.
Time-bounded foresight — declare a fact that only holds for a window; search filters
it out automatically once it expires (or before it starts):
set_foresight { "content": "Code freeze on main until the 0.17 cut",
"valid_until": "2026-07-01T00:00:00Z" }
// A later hybrid_search for "freeze" surfaces it (result_type: "foresight") only
// while valid; set valid_until in the past and it is dropped before fusion.
Consolidation scenes — when 3+ related entities cluster, consolidation folds them into
a durable scene (a coherent unit with a member-centroid embedding). A search that matches
the scene returns it and expands to its member entities — including members that didn't
match the query on their own — so you recall the whole cluster, not loose fragments. Scenes
match both lexically and semantically (cosine vs. the centroid).
Workspace profiles — each consolidated session gets a compact profile (active entities,
repo/branch/task context) that hybrid_search injects as always-on context, so every query
starts with the session's frame.
Retrieval traces — every search durably records its query, candidate sources, and
results, enabling offline tuning of fusion weights and regression detection.
Measured impact of the recall-quality controller on the evaluation corpus: precision
0.40 → 1.00, context clutter 0.75 → 0.00, accepted tokens 840 → 210 (≈4× leaner),
with recall held at 1.00.
Skills
The skills/ directory ships portable agent skills (slash-command
playbooks) that the installer copies into your agent skill directory
(~/.claude/skills/ by default; --no-skills to opt out):
/memory-session-start — restore context (check_intentions + hybrid_search) at session start
/set-foresight — declare a time-bounded fact
/consolidate-wrapup — force a consolidation pass at the end of a session
/defer, /whats-next, /roadmap — capture and surface follow-up work (needs the forge companion task board)
# Create a config file
cp examples/ferrosa-memory.toml ./ferrosa-memory.toml
# Edit contact_points to your Ferrosa instance
# Run
cargo run --bin ferrosa-memory-mcp
Run (Shared HTTP mode)
cp examples/ferrosa-memory-http.toml ./ferrosa-memory-http.toml
cp examples/http-auth-single-tenant.toml ./http-auth.toml
# Update TLS paths, contact points, graph URL, and the single auth principal.
# This example maps ferrosa_user to the default stdio tenant, preserving data
# already written with config/ferrosa-memory.example.toml.
FERROSA_MEMORY_CONFIG=./ferrosa-memory-http.toml cargo run --bin ferrosa-memory-mcp
# Listens on port 8765 by default and exposes:
# GET /health
# GET /healthz/live
# GET /healthz/ready
# POST /mcp
For a binary install, do not replace the generated
~/.ferrosa/config/http-auth.toml with the repository example. The installer
provisions that file and the installed config with one matching per-install
tenant. The HTTP-auth comments in
~/.ferrosa/config/ferrosa-memory.toml contain the exact reconciliation
command to run after changing transport or auth settings. The published
templates are available without a source checkout at
~/.ferrosa/share/ferrosa-memory/examples/.
For a shared deployment with separate tenant data, start from
examples/http-auth.toml or
examples/http-auth-multi-tenant.toml.
Seed or migrate data into each listed tenant before clients connect; principal
credentials select that tenant and cannot see the local single-user tenant.
Shared HTTP startup is fail-closed. The binary refuses to bind the listener unless all of the following are true:
server.require_tls = true
server.cert_path and server.key_path are set
server.auth_file is set
server.tenant_id is omitted
For a source checkout, run ./setup.sh --config <path> after building or
upgrading. Setup reconciles the per-install tenant across the HTTP auth file,
[viz].tenant_id, and agent-hook environment before restarting the service;
it removes obsolete server.tenant_id fallbacks from HTTP configs. Hook
verification sends a representative per-turn write and fails the setup rather
than claiming success when that write is rejected.
Probe semantics differ on purpose:
GET /healthz/live reports process liveness only
GET /health is an alias of /healthz/live
GET /healthz/ready reports whether the Ferrosa-facing data-plane clients are currently ready for MCP traffic. Under the role-aware boundary, that means auth + app-table CQL + enabled public query endpoints are healthy. It must not require graph-table MODIFY to report ready.
The shared HTTP template keeps viz disabled. If you enable it under HTTP mode, the viz listener stays loopback-only and requires an explicit [viz].tenant_id.
For Podman-based container startup on macOS, prefer PODMAN_COMPOSE_PROVIDER=podman-compose
so podman compose does not delegate to Docker Desktop's docker-compose.
Start On Login (macOS)
./scripts/install-launch-agent.sh
This installs a per-user launchd agent that, at login:
Draft clients can use the per-request HTTP protocol by adding the modern protocol headers and _meta fields to each JSON-RPC request. Start with server/discover:
A successful discovery response advertises tools, prompts, resources, and subscriptions/listen. See docs/mcp-draft-support.md for complete examples, including tools/call, prompts/get, resources/read, and workspace task updates.
Database Setup
Apply the DDL scripts against your Ferrosa instance:
Default result count for retrieval tools when k/limit is omitted
[eval]
Eval harness settings such as BRIGHT-Pro/MemoryBench retrieval_k
[embeddings]
Provider (Ollama/OpenAI), model, dimensions
[security]
Audit log, anomaly detection, sigma threshold
[routing]
Guideline version, feedback export schedule
Current local defaults:
Live retrieval keeps [retrieval].default_limit = 10 so ordinary agent turns do not overfill context. Agents or users can lower it at runtime with the config MCP tool when token use is too high.
Semantic retrieval uses Ollama nomic-embed-text-v2-moe with 768-dimensional embeddings when Ollama is available. If the embedding provider is absent, the server logs a warning and continues with lexical, phonetic, graph, and exact lookup behavior.
The live LLM judge/reranker is enabled by default with local Ollama qwen2.5-coder:7b. If that model or endpoint is unavailable, retrieval still returns the fused baseline results and reports the judge failure in rerank diagnostics; set [judge].enabled = false to opt out explicitly.
0.13 Long-Recall Evaluation Profile
The best-known BRIGHT-Pro support-doc-closed MCP slice profile as of the 0.13 preview is:
On the 200-document biology support-closed slice, that measured:
Metric
Score
alpha_nDCG
0.816
NDCG
0.799
aspect_recall
0.940
recall
0.796
Use the helper scripts to reproduce and extend the runs:
# Deterministic harness self-test
scripts/run-official-evals.sh --self-test
# Fusion/decomposition ablations against an already-ingested MCP slice
FMEM_EVAL_QUERY_DECOMPOSITION=llm \
FMEM_EVAL_QUERY_EMBED_VARIANTS=true \
scripts/run-fusion-ablations.sh
# Start a resumable full-corpus BRIGHT-Pro MCP ingest with heartbeat files
scripts/start-bright-pro-full-load.sh
Full-corpus BRIGHT-Pro currently contains hundreds of thousands of support documents. The loader writes heartbeat.json, progress.json, and load.log under diagnostics/eval-runs/... so overnight runs can be checked without attaching to the process.
http-auth.toml currently stores lowercase SHA-256 password digests. viz is disabled by default for the shared HTTP template; if you enable it under HTTP mode, set [viz].tenant_id and keep it on the loopback-only listener.
# Format, lint, test
cargo fmt
cargo clippy --workspace -- -D warnings
cargo test --workspace
# Coverage
cargo llvm-cov --workspace
# Docs
cargo doc --workspace --no-deps
CI runs on every PR: format, clippy, build, test + coverage (80% gate), complexity analysis, and doc generation.
Contributing
Contributions welcome. See CONTRIBUTING.md for the development
workflow and what we accept. By contributing, you agree to the
Code of Conduct.
Security issues should be reported privately — see SECURITY.md.
License
Ferrosa Memory is licensed under the Apache License, Version 2.0.
See LICENSE and NOTICE for details.
Copyright 2026 Ferrosa, Inc.
F
Ferrosa Memory
ferrosadb·7 estrelas·
Ferrosa Memory is an MCP-native memory server. Typed facts with history, plans, skills, graph relationships and folded context — returned by meaning, keyword, sound, or graph traversal. Forgetting is
Ferrosa Memory is an MCP-native memory server. Typed facts with history, plans, skills, graph relationships and folded context — returned by meaning, keyword, sound, or graph traversal. Forgetting is auditable and reversible.
Ferramentas
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Ferrosa Memory?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Ferrosa Memory usa?
Ferrosa Memory roda localmente via stdio.
Quando Ferrosa Memory foi verificado pela última vez?
Última verificação: 2026-10-28. Ferrosa Memory is an MCP-native memory server. Typed facts with history, plans, skills, graph relationships and folded context — returned by meaning, keyword, sound, or graph traversal. Forgetting is auditable and reversible.