Engram - Cognitive Memory Engine

Inspiration

Every "memory" solution we tried was actually retrieval: stuff text in a vector store, hope top-k finds it. But memory isn't lookup. Real memory changes — beliefs get revised when the world contradicts them, experiences get distilled while we sleep, unused details fade, and painful failures become rules we never break again. We wanted an agent whose memory behaves like a mind — and we wanted to make that visible, because seeing a belief snap from "Sara lives in Paris" to historical, with a validity interval, is worth a thousand benchmark tables.

What it does

Engram is a memory engine any agent can plug into through five calls: remember, recall, sleep, forget, inspect. It maintains three memory types:

Episodic — every interaction, timestamped, write-ahead-logged, decaying over time.
Semantic — a knowledge graph of facts with confidence, validity intervals, provenance, and status (ACTIVE / HISTORICAL / DISPUTED). When new information contradicts an old belief, Engram closes the old fact's validity interval, promotes the new one, and records the rationale — so it answers both "where does Sara live?" and "where did Sara live before?" correctly. Ambiguous conflicts become DISPUTED and the agent asks you to resolve them.
Procedural — behavioral lessons distilled from failure→correction patterns, injected into future turns, each carrying its own applied/helped scoreboard.

A sleep cycle clusters episodes, distills facts and lessons, compresses dozens of episodes into a few hundred tokens, and retires what decayed below the floor. Each agent turn gets a recall packet under a hard token budget, assembled by spreading activation over the graph — the model never sees full history, and the run log proves it. Two agents share the semantic graph: what Agent A learns, Agent B knows after a sleep.

All of it renders live on the living memory graph: salience is brightness, recall is a spreading glow, decay is a slow fade, sleep visibly streams episode dots into new fact edges, and a revision flashes the old edge into dashed-historical while the new one draws in. A timeline scrubber time-travels through the whole memory's life. A one-click benchmark runs the same scenario through full-history, naive RAG, and Engram, LLM-grades the answers, and shows accuracy vs token cost.

How we built it

Python stdlib backend (zero dependencies — judges can run it with one command), JSON event sourcing so the UI, the timeline, and Demo Mode all replay the same truth, and an HTML5 canvas frontend with force-directed layout. All model calls (extraction, belief revision judgment, consolidation, agent replies, grading) go through one OpenAI-compatible gateway pointed at Qwen on Alibaba Cloud (DashScope); decay math is deterministic and unit-tested. Demo Mode replays a genuinely recorded live run — labeled as such — so the 3-minute story survives any network conditions.

Challenges we ran into

Belief revision is judgment, not string matching ("moved to Casablanca" must contradict "lives in Paris" but not "likes Paris"); free-tier rate limits forced a global throttle with retry-aware backoff; and making the visualization honest — every pixel maps to a real engine variable — was harder than making it pretty.

Accomplishments we're proud of

The revision moment: contradiction detected, validity interval closed, rationale recorded, temporal question answered correctly — live, on screen. And the benchmark telling an honest story: near full-history accuracy at a fraction of the tokens.

What we learned

Memory quality is mostly about forgetting well: decay, consolidation, and revision matter more than storage. And token efficiency falls out naturally once recall is a budgeted, activation-ranked packet instead of a transcript dump.