Memory & Graph
Worker memory
beyond a single run.
A self-hosted semantic store in SQLite, influenced by mem0 / Memora patterns: scoped hybrid search, append-only versioning, secret detection and an entity graph that workers can use across runs.
memoring · absorbing facts
What is stored
Self-contained facts, scoped
Each record is a self-contained fact with scope isolation — agent (shared knowledge), user (about the client), run (session episode). Confidence, importance, tags, typed edges and a change journal help workers inspect and update context.
| Field | Purpose |
|---|---|
| content | the fact text |
| scope | agent · user · run |
| confidence | 0.0–1.0 tie-breaker |
| importance | weight, grows via memory_boost |
| status | active · superseded · archived |
01Principles
Patterns for durable worker context
Append-only
Append-only mode records a new version as a new record plus a supersedes edge; contradictions can remain visible through contradicts. Read modes include active, latest and full_history.
Absorb, not create
Secrets can be rejected before consolidation, deduplication and similarity checks classify an item as duplicate, supersede, contradict, related or new. Use dry_run to inspect an absorb plan before writing.
Hybrid search
score = 0.7·cosine + 0.3·BM25, then freshness decay. Latency depends on the local store, embeddings configuration and workload; consult benchmarks for measured environments.
Digest before start
A worker can receive a deterministic digest in its system prompt: relevant memories, open TODOs and recent records with ids for verification.
Optional rerank
[memory] rerank = true: when configured with a compatible model, a second LLM pass can re-order an expanded result set by relevance.
Embeddings with fallback
Auto mode can use a configured OpenAI-compatible /embeddings endpoint; without one, the local TF-IDF fallback keeps indexing offline. Vectors from different models are kept separate.
02Memory tiers
Profile, skills, archive
A compact stable profile that can be included in the system prompt for consistent worker context and efficient caching.
Procedural knowledge discovered from experience (create_from_experience), injected on demand via the skill tool.
The SQLite knowledge base on this page — hybrid search, graph and versioning, sized by local storage and operator policy.
Entity graph
person ↔ company ↔ location
Alongside facts, the store maintains a directional entity graph: nodes (person, company, project, technology, role, location, event, product), typed edges (works_at, leads, founded…) and sub-2ms multi-hop recursive queries in SQLite.
memory_graph add · query · list
Fig 4.1 — Enterprise Entity Knowledge Graph: 3-hop relationship traversal across 5,420 interconnected entities in 1.62 ms with zero cloud Vector DB fees.
OSINT integration
Memory for research workflows
When a configured research or lead-generation workflow opts in, the entity graph can connect people to companies, locations and industries. Multi-hop queries support questions like "who leads companies in Kazan". Absorbed contacts become queryable context for later worker runs.
# After a lead-gen run, contacts are auto-absorbed
fathom memory search "CTO fintech Moscow"
# → Ivan Petrov, CTO, PayTech (conf 0.92)
# → Maria Kozlova, CTO, FinBox (conf 0.87)
# Entity graph queries are available to agents through memory_graph
# memory_graph(action="query", query="companies in Kazan")
# → Acme Corp → works_at → Ivan Petrov
# → leads → Engineering → located_in → Kazan03Agent tools
Tools for one memory store
Ingest facts through the absorb pipeline; configured workflows can save discovered contacts without requiring a model-generated write.
Hybrid vector + BM25 search with scopes, filters and freshness decay.
Build the pre-run digest (relevant + TODOs + recent).
Raise importance of facts that keep proving useful.
Create typed edges between records.
Add/query/list entities and relations.
Housekeeping
Distill and manage retention
CLI memory search / list / get / stats / rebuild / distill / nuke. Distillation can compress run facts into durable knowledge. GC can archive expired or stale run facts and compact scope groups according to retention settings; review destructive operations before running them.
fathom memory search "fintech leads Kazan"
fathom memory stats
fathom memory distill
fathom memory gc --dry-run