git-engram

The repo's commit graph as the agent's memory.

Every memory system for coding agents stores knowledge next to the repo — per-machine files that don't travel, don't merge, and go stale silently. git-engram stores it in the repo, on git's built-in but nearly forgotten git notes mechanism:

• Engrams — durable repo-truths anchored to the commit that established them (refs/notes/engram). Recall is topology-based: working on a file surfaces only memories anchored in that file's own history. When the code is rewritten, its memories age out naturally.
• Letters — session digests attached to branch heads. The next session on the branch (yours or a teammate's) reads its predecessors' letters. Memory follows the work, not the machine.
• Scars — mined from raw history with zero writes: reverted commits (tried and undone), files fixed repeatedly (fragile), churn hotspots.

One git-engram sync pushes/fetches the notes refs — memory becomes team-distributed with union-merge semantics (cat_sort_uniq): concurrent memories from two teammates never conflict, by design. No server, no database, no infrastructure. git log --notes=engram shows the raw storage.

Quick Start

Install the git-engram skill in the Agent Skills format with npx skills:

npx skills add oasissys/git-engram --skill git-engram -g

The skill teaches your agent to recall at session start, remember repo-truths as it learns them, and leave a letter before ending. It runs the CLI without a global install via npx -y @oasissys/git-engram.

Other ways to install

Ambient memory on every session

npm install -g @oasissys/git-engram
git-engram setup        # SessionStart recall + SessionEnd auto-letter (Claude Code, Codex, OpenCode)
git-engram setup-repo   # per-repo: plain `git fetch` brings teammates' memories along

Because the bin is named git-engram, git's own subcommand discovery makes git engram <cmd> work too.

Zero setup

Execute `npx -y @oasissys/git-engram` to read this repo's agent memory.

Use

git-engram                                                    # this repo's memory: engrams, last letter, scars
git-engram remember "build.sh does not deploy to cache" --file build.sh
git-engram recall --file src/toon.ts                          # memory scoped to one file's history
git-engram letter --write "release 0.2.2 live; CI verify pending"
git-engram scars                                              # what history warns about
git-engram at v0.2.0                                          # time-travel: what did we believe then?
git-engram sync                                               # exchange memory with the team
git-engram gc --apply                                         # prune memories whose anchors left history

Output is TOON on stdout, diagnostics on stderr, exit codes 0/1/2 — built for agents (AXI).

The protocol in one diagram

commit graph            refs/notes/engram             refs/notes/engram-letters
    ●───●───●───●  HEAD      │                              │
    │       │                ├─ "wrapper must restore       └─ "session ended on main;
    │       └─ anchored ─────┤   sentinel LAST"                 sqlcl fix pending review"
    └─ anchored ─────────────┴─ "build.sh doesn't deploy"
         ↑ recall --file build.sh walks THIS file's history and finds only its memories

Development

pnpm install && pnpm run build
pnpm test                # 20 e2e tests against throwaway git repos
pnpm run lint
pnpm run build:skill     # regenerate SKILL.md (CI fails if it drifts)

Releases are cut by release-please from conventional commits on main and published to npm by CI. Do not hand-edit CHANGELOG.md, .release-please-manifest.json, or skills/git-engram/SKILL.md — they are generated.