Every feature, in full.

The complete surface, with the numbers that back each claim and the command that reproduces them. The overview is the short version of this page.

pip install iai-pme GitHub PyPI

Finding a memory Staying accurate Token economy The nightly cycle Ambient capture Teaching it files The dashboard The terminal Operations Your data The engines The fifteen tools Scope

Finding a memory

Five ways in, each one suited to a different kind of question. All of them answer straight from the local store, with the model kept out of the loop.

Route	Entry point	What it is for
By cue	memory_recall	Similarity, graph strength and recency fused in one pass. Contradicting memories return alongside matching ones.
By time	memory_temporal_recall	“What did I say about pricing in May?” Every record carries the window it was true for.
By shape	memory_recall_structural	Matches the structure of a memory, so you can find one whose wording you have forgotten.
By text	memory_search	Keyword search over the record surface, fused with the semantic lane.
Engine asleep	iai-mcp bank-recall	Reads the store directly. Recall keeps working while the engine rests.

Every response reports how it was produced: the token budget it respected, whether the cue was read as literal or conceptual, which pattern triggered that reading, and the latency. A degraded run announces itself.

Finding the right memory: R@5 0.962 · python -m bench.longmemeval_blind

Staying accurate over months

The whole design rests on one promise: what you said is what comes back, and every version you ever held stays on the record.

Moments are written once and kept as written. A correction arrives as a new record with a link, so the original survives intact.
When a fact changes, the superseded one is filed with the window it was true for. Both stay reachable, and the current one arrives marked as a replacement.
Each capture carries a content fingerprint, so a replayed transcript is recognised and stored once.
Every memory arrives with its age and how many times it has been revised, so the assistant can weigh it.
Encryption happens on the way in. The only path into the store is the encrypted one.

A replaced fact stays reachable: 1.000 · its original wording survives: 1.000 · python -m bench.contradiction_longitudinal

Token economy

Memory pays for itself. An assistant that has forgotten something goes hunting for it, and that hunt is what memory replaces.

An injected pack averages ~350 tokens against ~2,850 for the agent search it displaces: about 88% cheaper per pack served.
What arrives at session start stays inside a fixed budget, measured at 1,629 minimum and 2,993 standard against a 3,000 ceiling.
The engine tells your assistant to clear stale traffic of ours once the conversation crosses 30,000 input tokens, so old tool calls stop riding along.
Every recall respects a token ceiling, 1,500 by default, so a response stays the size you asked for.
Long summaries are compressed before storage. Your own words stay whole.
The dashboard counts packs served, tokens injected and tokens saved, from your own store rather than from an average.

Session-start cost: 1,629 min / 2,993 std · python -m bench.tokens

The nightly cycle

The heavy work waits for you to step away. The engine learns when that usually happens and books itself into that window.

Sleep runs in stages, from awake through drowsy to deep, driven by whether you are at the keyboard.
Captures drain on the way down and again after each cycle: shield, embed, deduplicate, encrypt, store.
Consolidation groups related episodes, writes summaries from them, strengthens the paths you keep using and lets the rest fade.
At most one model call a night, through the Claude subscription you already pay for, capped at 1% of your daily quota.
Questions are minted only when two leading memories genuinely disagree, and the question names both sides word for word.
Tomorrow’s first pack is assembled tonight, so the next turn arrives already answered.

Ambient capture, six assistants

One command wires every assistant on the machine. From then on it records as you work.

Assistant	What it gets
Claude Code	Recall at session start, recall before each turn, turn capture, session capture
Codex	The same four, registered in its own hook file
Cursor	Session-start recall and full capture
Antigravity	Recall on each invocation, capture from the full transcript
Hermes	Recall before each model call, capture at session end
OpenClaw	The memory tools, available on request

Recording a turn is a file append: about 5 ms, with the engine left alone.
A missing store or a resting engine yields an empty prefix, so your session starts on time regardless.
Re-running the installer is safe, and a config written by somebody else is left alone with the block printed for you to place.

Teaching it directly

Drop a file in and it studies it: splits it into passages, weaves them into what it already knows, keeps one copy of anything familiar, then verifies that it can recall what it just read and reports the difference.

Accepted: .txt .md .markdown .rst .tex .bib .csv .pdf .docx .pptx .xlsx .rtf .epub

Office documents are read straight from their container, and the PDF reader loads only when a PDF actually arrives.

The dashboard

A live map of the memory, and every control on it does real work. iai brain opens it locally.

Search the store and watch the graph collapse to that memory’s neighbourhood, with its tier, tags and timestamps.
Pin keeps a memory for good. Fade hands one to the next sleep cycle. Rescue pulls it back while the ring is still flashing.
Drop a file and watch it split, weave in, verify and report.
Folders build themselves by time, topic, teaching and conversation.
Disagreements draw as red links between the old fact and the current one.
Engine controls: consolidate now, sleep, wake, restart.
The live token economy: packs served, tokens injected, tokens saved.
The same dashboard ships as a desktop app for macOS and Linux.

The terminal

Two commands. iai is for asking memory things. iai-mcp is for running it.

iai        recall · temporal-recall · search · ask · capture · teach · upload ·
           watch · brain · status · last

iai-mcp    doctor · self-update
           daemon {install,start,stop,restart,logs,pause,resume,stats,configure}
           crypto {init,status,rotate,migrate-to-file,recover-with-prior-key,
                   redact-undecryptable}
           maintenance {compact-hippo,compact-records,idem-dedup,edge-backfill,
                        schema-cleanup,sleep-cycle}
           capture-hooks {install,uninstall,status} · cowork · lifecycle ·
           migrate · build-native · audit

iai watch keeps a folder in step: it rescans every thirty seconds, restudies what changed and retires what you deleted.

Looking after itself

27 checks on demand, covering the engine, the store, the native core and the runtime state. Each one reports pass, warn or fail on a single line.
It repairs what it finds. Prompted repairs ask before touching memory, and damaged state files are renamed aside so the engine rebuilds them.
Your assistant runs the unattended subset for you when the engine stays quiet ten seconds into a session, so a stalled engine tends to fix itself before you notice.
iai-mcp self-update upgrades the package, restarts the engine and proves the restart by asking the running engine its version.
A daily background check reports a new release as a doctor row and one line at session start, then waits for you to say go. IAI_MCP_VERSION_CHECK=0 turns it off.
Maintenance is one command each: compaction, deduplication, edge backfill, schema cleanup, and a sleep cycle on demand.

Your data, your keys

Every record on disk is encrypted with AES-256-GCM. The key lives in your home folder, readable only by you.
Rotate the key whenever you like, and recover with the previous one if you rotated too early.
The engine listens on a local socket only, so it is reachable from your machine alone.
It runs account-free, sign-up-free and telemetry-free. The one thing that leaves your machine is the model call your assistant was already making.
Deleting the folder deletes the memory. That is the whole story.
Swap the text model for one of your own over a local endpoint, which is how you take it into another language.

What runs it

Four pieces do the load-bearing work, and all four are ours.

Hippo — the store

Records, search index and the connections between memories in one encrypted file. Written for a graph that changes every night.

MOSAIC — the sorting

Works out which memories belong together. A Leiden-family method on the CPM objective, rewritten in permissively licensed Python so the whole project stays MIT.

Lilli HD — the substrate

Gives moments, knowledge and habits their own representation in one store, which is how you find a memory by its shape.

The native core

Rust: the embedder and the graph kernels. This is where the speed comes from.

Underneath sit boring, audited, permissively licensed pieces: the encryption, the tensor library and the numerical stack are other people’s excellent work, deliberately.

The fifteen tools your assistant can call

memory_recall · memory_temporal_recall · memory_recall_structural · memory_search · memory_capture · memory_contradict · memory_reinforce · memory_consolidate · profile_get_set · topology · schema_list · events_query · episodes_recent · curiosity_pending · camouflaging_status

The engine also tells your assistant when to reach for memory: ask it first for decisions, preferences, past discussion and rationale, and keep file search for the current state of the code.

Where the line is

Worth saying plainly, so you know what you are getting.

It serves memory rather than source. Reading the current state of your code stays the job of your assistant’s own file search.
Summaries are induced alongside the verbatim record, which stays the authority.
macOS and Linux are fully supported. Windows is in beta.
Everything is MIT and complete as shipped.

pip install iai-pme Back to the overview