A hands-on guide to putting Ferrosa Memory to work in a real agent loop — ingest your codebase once, retrieve instead of grepping, link what relates, record decisions as they evolve, and forget on purpose.
Day-to-day, Ferrosa Memory comes down to a short loop. Ingest what you learn, retrieve before you do work, link facts that relate, record facts as they change, and forget deliberately when something is wrong or stale. The MCP tool names map straight onto these verbs.
{
"tool": "smart_ingest",
"arguments": {
"entity_name": "Auth token rotation",
"entity_type": "decision",
"content": "Access tokens rotate every 15 min; refresh tokens are single-use and stored hashed."
}
}Store insights, decisions, relationships, and facts — not raw file contents. smart_ingest deduplicates against what's already there and supersedes when it recognizes an update.
{
"tool": "create_edge",
"arguments": {
"from": "Auth token rotation",
"to": "Session store schema",
"edge_type": "depends_on"
}
}After learning two related facts, link them. Edge types include depends_on, contains, part_of, related_to, calls, implements, uses, and references.
{
"tool": "hybrid_search",
"arguments": {
"query": "how do we rotate auth tokens",
"limit": 5
}
}If hybrid_search returns what you need, you're done — no grep, no find, no re-reading files. For document-chunk hits, call get_chunk_context to expand around a match and recover the surrounding lines.
{
"tool": "write_temporal_fact",
"arguments": {
"entity_id": "<entity UUID from smart_ingest>",
"fact_text": "Rotation window changed from 15 min to 10 min."
}
}Temporal facts are timestamped and superseded rather than overwritten. Retrieval returns the latest value by default; the full chain stays inspectable for audit.
forget with a query to propose candidates and see each one's blast radius, then call it again with confirm: true and the IDs you approved. The default mode is a reversible retraction (restore with restore_forgotten); a hard delete is permanent. Never confirm on a user's behalf.The single most useful habit: ingest your whole codebase and docs into memory once, then let the agent retrieve the relevant functions and files semantically — instead of grepping, listing directories, and re-reading whole files at the start of every session.
Walk the source tree and feed files through smart_ingest (or batch_ingest for bulk). Documents are stored as a document → section → chunk hierarchy with semantic previous/next links, so a single hit can be expanded back into full surrounding context. Re-run only on the files that changed to keep memory fresh — you don't re-ingest the world every session.
Next session, the agent asks hybrid_search "where do we validate refresh tokens?" and gets the exact function back — fused from vector, lexical (BM25), phonetic, and graph signals. No directory listing, no full-file re-read to locate one symbol. When a chunk hit needs its neighbors, get_chunk_context pulls the adjacent chunks.
Memoization caches the results of completed, deterministic sub-calls by content hash. When the same sub-task recurs, the prior result comes back from cache instead of paying for a redundant LLM call. And session-restore hooks mean the agent opens each session already knowing what it was doing — it doesn't re-derive context it computed last time.
Ferrosa Memory exposes around 80 MCP tools — but it doesn't hand them all to the model at once. They're organized into two tiers and disclosed progressively: a small, focused everyday set is exposed by default, and the fuller toolbox is revealed when the task reaches for it.
The everyday memory loop: smart_ingest and hybrid_search, typed edges, context expansion, triggered intentions, durable session tasks, feedback, stats, runtime config, and forget. This is what the agent sees first.
Batch work, memo & plan tracking, the full intention lifecycle, trajectory folds, bi-temporal facts, stored skills, consolidation and graph inference, and the governance plane — surfaced by passing include_all: true on tools/list.
To reveal Tier 2, your client sends include_all: true on the MCP tools/list request; the all_tools tool also enumerates the full catalog from inside a session. The agent effectively "graduates" to more tools as the work demands them.
// default — focused everyday set
{ "method": "tools/list", "params": {} }
// reveal the full toolbox when the task needs it
{ "method": "tools/list", "params": { "include_all": true } }Every tool definition the model sees is text in its context window. Loading a focused default set instead of all ~80 schemas means fewer tokens spent on tool definitions before the agent has done any work.
A shorter, focused list is easier for the model to choose from correctly. The advanced and operator tools stay out of the way until a task actually calls for batch work, folds, or the governance plane — then they're one flag away.
The same loop supports very different jobs. Here are three concrete ones.
Ingest the repo and docs once, and record decisions as they're made. Next session, the agent runs check_intentions and a hybrid_search at startup, opening with what it already knows — the codebase map, the open decisions, and where it left off — before reading a single file.
Ingest papers, articles, and your own notes as you go; link findings with create_edge so related ideas connect instead of piling up. Background consolidation surfaces relationships between notes that arrived separately, and hybrid_search recalls them by meaning later — not just by the words you happened to use.
Point several agents or teammates at the same Ferrosa Memory instance and they share one graph: a decision recorded by one is retrievable by all. Durable session tasks — a focus stack, working set, and recovery hints — survive restarts and support handoff, so an interrupted agent (or a colleague's) can pick up where the last left off.
Memory is only as useful as the loop around it. These habits keep recall sharp and the graph trustworthy.
smart_ingest deduplicates and supersedes, so refreshes don't bloat the graph.hybrid_search the first move, not a fallback. If it answers, you're done; if the first page misses, send +1/-1 feedback and page on before reaching for grep.smart_ingest or write_temporal_fact and link it. Tomorrow's agent reasons over decisions, not just files.create_edge between them. Connected facts are knowledge an agent can traverse; isolated facts are just data.forget — propose, review blast radius, then confirm. Prefer reversible retraction; every removal is journaled, so it's a deliberate act, not a guess.Install the server, connect your MCP client, and wire the session hooks so recall and capture happen automatically. The Setup guide covers ports, embeddings, credentials, and harness hooks end to end.
Want to know how the fused ranking, bi-temporal facts, dream-cycle consolidation, and auditable forgetting actually work? The How it works page walks the architecture layer by layer.
Start by ingesting one repo and asking it a question. Then add the session hooks so the loop runs itself.