Agent Memory (Fractal)

Core Philosophy

1. Fractal compression — Memories auto-consolidate into parent summaries as the graph grows; infinite scale without infinite storage.
2. Semantic recall — Vector similarity search returns the most relevant memories for a query, not just keyword matches.
3. Human-like hierarchy — Memories form a tree: leaf nodes (raw events) → parent nodes (summaries) → root (compressed context).
4. Auto-consolidation — After N orphan inserts, background consolidation fires automatically.
5. REST-first — FastAPI server; no MCP SDK dependency — call via HTTP from any agent.

Quick-Start: Common Problems

"Remember this context"

POST /remember
{ "text": "User prefers TypeScript over JavaScript", "metadata": { "source": "conversation", "importance": 0.8 } }

Returns: node_id, level, parent_id

"What do I know about X?"

GET /recall?q=TypeScript preferences&top_k=5

Returns ranked memories with similarity scores and graph paths.

"Browse the memory graph"

GET /navigate?node_id=<id>   # or GET /navigate for root

Returns node content + children for visual/programmatic traversal.

"Trigger consolidation manually"

POST /admin/consolidate

Merges orphan leaf nodes into summaries using the configured LLM.

Decision Trees

Task	Endpoint	Method
Store a memory	/remember	POST
Semantic search	/recall?q=...&top_k=N	GET
Browse graph	/navigate	GET
Get node by ID	/navigate?node_id=...	GET
Get all nodes	/nodes	GET
Manual consolidation	/admin/consolidate	POST
Server health	/health	GET

Reference Index

File	Contents
(no references)	All documentation is self-contained