engram

engram is a personal wiki that a language model writes and keeps up to date for you. You add sources; the model reads them and maintains a set of linked markdown pages. The files use the Open Knowledge Format (OKF), so a wiki is just plain markdown in a folder — nothing proprietary, readable in any text editor and browsable in Obsidian.

This package is the engram command line tool. It does the mechanical work: creating a wiki, checking it, building the index, searching, linking, and tidying. It never calls a language model itself. The thinking — reading sources, writing pages, answering questions — is done by a Claude Code agent that follows the CLAUDE.md file inside each wiki. The tool is the hands; the agent is the head.

How it fits together

you ── add a source ──▶  Claude Code agent  ──uses──▶  engram (this tool)
                         reads CLAUDE.md              validate · index · search
                         writes the pages             links · lint · move · log

• You drop a source into the wiki and say "ingest this".
• The agent reads it, writes a summary and the pages it touches, and links everything together — following the routines in CLAUDE.md.
• engram keeps it all honest: it checks the format, rebuilds the catalog, finds broken links and orphans, and searches — deterministically, the same way every time.

The three layers

• sources/ — the raw material you add, saved once and never edited again.
• wiki/ — the markdown the model writes: one summary per source, plus pages for people, ideas, comparisons, and answers, all linked together. The tool keeps wiki/index.md and wiki/log.md current.
• CLAUDE.md — the instructions that turn the agent into a careful wiki keeper: the rules, the per-type frontmatter, and step-by-step routines for adding a source, answering a question, and health-checking the wiki.

Install

npm install -g @jeromeetienne/engram

Requires Node.js 18+. Or run it without installing:

npx @jeromeetienne/engram init my-wiki

Quick start

engram init my-wiki          # create a new, empty wiki (just a folder)
cd my-wiki

Then, from Claude Code inside the folder, add a source and ask the agent to ingest it. The agent will use the commands below and leave the wiki valid, indexed, and linked. To see where things stand at any time:

engram status                # a dashboard: pages, sources, links, last log
engram validate              # is the folder a well-formed wiki?
engram lint                  # broken links, orphans, stale pages, ...

engram init --git also starts a git repository with a pre-commit hook that runs validate and lint before every commit.

Commands

Set up and check

| command | what it does | | --- | --- | | engram init [dir] | create a new wiki (a folder) | | engram validate [path] | check the folder is a well-formed OKF wiki | | engram lint [path] | report broken links, orphans, stale pages, duplicates | | engram status [path] | a dashboard of the wiki |

Write and maintain

| command | what it does | | --- | --- | | engram new <type> <id> | create a page from its type template | | engram fmt [path] | tidy frontmatter and rewrite links to relative form | | engram move <old> <new> | rename a page and fix every link and reference to it | | engram index [path] | rebuild the index.md catalog files | | engram log <verb> <message> | append a dated entry to log.md |

Find and navigate

| command | what it does | | --- | --- | | engram search <query> [path] | search the pages (BM25 over title, description, tags, body) | | engram ls [path] | list pages, filter by --type or --tag | | engram links <id> [path] | a page's inbound, outbound, and broken links | | engram show <id> [path] | a page's frontmatter and links | | engram whois <name> [path] | resolve a name or alias to matching pages | | engram reindex [path] | rebuild the search cache under .engram/ |

Most read commands take --json for scripting. Run engram <command> --help for the full options.

About the format

A wiki is an OKF bundle: a folder of markdown files, each with a small YAML frontmatter block whose only required field is type. index.md and log.md are reserved and written by the tool. Links between pages are relative markdown links (like ../concepts/foo.md) — never absolute paths and never [[wikilinks]] — so the folder stays portable and readable anywhere.

The idea of a wiki that a language model keeps up to date comes from Andrej Karpathy's LLM wiki. The full spec and build plan is issue #2.

License

MIT © Jerome Etienne