Core concepts

Engram is opinionated about honesty. Four ideas do most of the work. None of them are complicated — they are just followed strictly, in places where most systems quietly cut a corner.

1. Provenance, not veracity

This is the foundation. A sealed record proves that something was recorded, in a particular form, at a particular time, and has not been altered since. It does not prove the content is true.

The distinction sounds pedantic until you see what it prevents. Imagine a page that says "the payment webhook retries three times." Sealing that page proves your agent genuinely wrote it down on a specific day and that nobody has edited it since. It does not prove the webhook actually retries three times — maybe it was two, maybe the code changed last week.

Engram never blurs this line. It is honest about what it can check (did we really record this, and is the record intact?) and honest about what it cannot (is the world still like this?). Sold as a "hallucination detector," a seal would be a lie. Used correctly, it attacks a specific, real problem: memory confabulation — an agent being unsure whether an event it "remembers" actually happened. With Engram, "show me the sealed record" becomes a check the agent can run on itself.

Every page also wears its evidence state openly:

• traced — someone checked this against reality (read the code, ran the test).
• inferred — reasoned, plausible, but not verified. The honest default.
• stale — it was checked once, but the thing it described has since moved.

Engram surfaces that state whenever it shows you a page. Nothing inferred is ever presented as established fact.

2. Index-first recall (recall beats grep)

When you ask a question, Engram does not scan your whole store. It reads a single catalog — a one-line summary of every page, organized by kind and project — picks the handful of pages that actually answer, reads only those, and hands them back with citations to where each came from.

Compare that to plain grep. Grep drags back every file that mentions your search words — a haystack of tens of thousands of tokens that something still has to read and sift. Engram reads one index, opens the two or three pages that answer, and stops.

The payoff is measured, not asserted: on a real store, broad questions read on the order of 86% fewer bytes into the context window than re-grepping the source — and that number is computed from the actual command and printed, never a figure you are asked to take on faith.

There is a deeper idea underneath the speed. Instead of re-discovering knowledge from raw sources on every question, Engram compiles what you have learned into an interlinked wiki once. So knowledge compounds: the answer to "why did we do it this way?" is a page that already exists, not a search you run again.

To keep this cheap as pages grow, Engram can split a sprawling page that covers many topics into smaller focused ones, so a narrow question pulls a small precise answer instead of a giant page.

3. Decay by evidence (trust is derived, never stored)

Here is a trap almost every knowledge system falls into: it writes a trust score into the record. "This page is 90% reliable." The moment the evidence underneath that page changes, the score is a lie — it was frozen at the moment it was written, while the world kept moving. You end up with confident, stale numbers: the worst kind.

Engram refuses to store trust. A page's freshness and trustworthiness are worked out fresh, from the evidence, every single time the page is read. Nothing is cached that can rot. There are three signals it derives:

• Is it still true? — from sealed vouching events, each bound to the exact text of the page. Edit the page and any prior vouch silently no longer applies; the page reverts to unverified. It cannot be faked by typing a date into the file.
• What kind of knowing is this? — an evidence-weighted spectrum, strongest wins: a page bound to a passing test, then one traced to a real source line, then one a human personally vouched for, then one corroborated by several independent pages, and finally plain reasoning. The rule that orders them is blunt and deliberate: verifiable bytes outrank human memory, and human memory outranks inference. A human vouch never outranks a checkable fact — memory and emotion make even a well-meaning person a fallible witness.
• Did it ever actually help? — a live count of the times a page was genuinely pulled into a session and used. This is derived from sealed usage events (each recall seals one), so it cannot be inflated by hand.

Crucially, usage never inflates trust. A page being popular does not make it correct; only evidence raises its standing. And a page that nobody verifies and nobody uses sinks in rank and quietly archives itself — it is never deleted. A future session can always re-open it on new evidence.

Symbol-first, and honest about it. Trust here is symbolic: explicit rules over explicit evidence, worked out on every read — nothing learned, nothing you can't inspect. That approach comes straight from the production systems Engram descends from (Titan AI and Mnemosyne). Separately, an optional embedding pass can suggest latent links between pages — a curation aid that helps you notice two pages belong together. It never touches recall and never overrides the evidence.

4. The sealed chain, and Bitcoin anchoring

Every page is hash-linked to the one before it, so your whole memory forms a single tamper-evident hash-chain. Change one word in a month-old page and the chain visibly breaks — the alteration cannot hide.

That catches casual tampering. To also catch a determined, wholesale rewrite (which could re-link every hash consistently and look intact on its own), Engram periodically takes the tip of that hash-chain and anchors it into Bitcoin's timechain — recording it against the most secure public clock there is. A rewrite cannot reproduce a value that was already committed to Bitcoin days ago, so it gets caught.

And this loops right back to concept #1. Anchoring proves when a thing was recorded and that it has not moved since — provenance, never veracity. It does not vouch that the content is correct. What it buys you is portable trust: any future instance, even on a brand-new machine, can verify a memory's authenticity and timestamp without having to trust the environment it is running in. That is the real prize — continuity you can check, not just protection against a local intruder.

Bitcoin anchoring is entirely optional and off by default in the sense that your memory works fully without it. It is there when you want cryptographic, environment-independent proof of when something entered your memory.

How the four fit together

Pages hold one durable thing each and link to each other like a wiki (concept #2's substrate). Their trust is derived live from evidence, never stored (concept #3). The whole thing is sealed into a tamper-evident chain, optionally anchored to Bitcoin (concept #4). And the thread running through all of it is the one rule from concept #1: prove provenance, be honest about veracity.

Next: see these ideas as commands in the CLI reference, or wire them into your editor in Using it in your editor.