local causal and temporal memory

a memory that
remembers why.

most stores hand back text that looks like your question. iglegais keeps why things happened and what is still true, in a single local file you run on your own machine.

$ pip install iglegais v0.9 · on pypi
a hand holding a laurel wreath
remembrance · laurel, oil on panel
the problem

a flat pile of vectors
forgets the story.

embed the text, store the vector, hand back the nearest match. that tells you what a memory looks like. it stays quiet on why the thing happened, and on whether it still holds. three separate questions, and a nearest-neighbor search fumbles every one.

the quiet failure is worse. ask it something it has no answer for and it still returns the closest row, at cosine 0.2, reported as fact. the retrieval layer was never given permission to say i do not know.

a hand drawing a bow
the aim · study of a drawn bow
the shift

memory,
kept as a graph.

every memory is a node: an embedding for meaning, a timestamp, and the subject it is about. the edges between nodes carry a type. caused by, contradicts, follows. the edges do the reasoning that similarity cannot.

so it walks a chain of causes down to a root, and it tells a live fact from a stale one, because it kept the edge that says one replaced the other. four hundred lines of sqlite hold the whole thing.

hands gathering pearls into a shell
what is worth keeping · pearls, detail
what it does

three questions a pile of
vectors cannot answer.

two hands reaching toward each other across a sky
one fact reaching for the next
I

why

walks the caused-by chain from a symptom to the true root, even when the root reads nothing like the question.

II

what is still true

subject slots retire stale beliefs with a foreign key, and as-of queries rebuild what you believed at any past moment.

III

it forgets on purpose

a background pass merges duplicates and writes the higher fact a cluster of small memories implies, so the store gets cleaner as it grows.

the engine

four hundred lines,
and it fits in one file.

no cluster, no vector database, nothing to boot. an mcp server and a python library sit over a single sqlite file. memories are rows, edges are rows, vector search is a dot product. everything below is the whole system.

interface
mcp server
seven tools an assistant calls directly. the model fills in the subject for free, so supersession needs no wiring.
python library
import MemoryGraph. remember, recall, why, whats_true, about, consolidate.
the engine ~400 lines of python
one class over sqlite. no orm, no network, no build step.
write path
embed to 384-d minilm, an llm infers the edges and subject from nearby memories, dedup at 0.97, a subject slot wires a contradicts edge to the prior belief, entities get indexed.
read paths
brute-force dot product or a sqlite-vec knn, a causal walk down caused-by, subject slots with as-of time travel, and rrf fusing vector, keyword and entity signals.
the dream pass
offline, it folds near-duplicates into a canonical node and synthesizes the higher fact a cluster implies, keeping edges back to every source. fires on a threshold, like lsm compaction.
one file on disk ~/.iglegais/memory.db
memories id · content · embedding · ts · subject · namespace edges src · dst · rel entity_links meta adds_since vec_memories float[384] · optional index
edge vocabulary caused_bycontradictsfollowsduplicate_ofsynthesized_from
namespaces isolate every user and agent · graceful uncertainty abstains below 0.35 cosine
built for builders

everything you need to build memory that reasons.

I
typed edges
caused by, contradicts, follows. relationships are first-class data.
II
temporal awareness
every memory is timestamped. query what was true at any past instant.
III
truth over similarity
subject slots return the current belief, past whatever reads closest.
IV
causal chains
trace an outcome back through its causes to the root that started it.
V
graceful uncertainty
a confidence floor lets it say i am not sure instead of guessing.
VI
plug and play
a python library and an mcp server. local runtime, no database to boot.
the proof

zero against one hundred,
reproducible in ten seconds.

on the two questions that decide whether an agent feels sharp or broken, a flat vector store scores a flat zero. the graph scores everything. the benchmark ships in the repo.

causal root cause · 8 incidents, each buried under 200 unrelated memories
flat vector
0
iglegais
0
current truth · 8 facts, each later reversed by an update
flat vector
0
iglegais
0
0
causal chains resolved
0
per query
0
model calls at read time
get it

two commands, and
your assistant has it.

no database to run, no server, nothing to boot. it installs as one package and keeps everything in a single file under your home directory.

# install
pip install iglegais

# wire into any mcp client
claude mcp add iglegais -- iglegais

# or use it as a library
from iglegais import MemoryGraph
mg = MemoryGraph()
mg.root_cause("why did the service fail to boot?")
a figure of light breaking through the dark
the next layer

your ai remembers.
now it understands.