khms-memory: Instructions file for Claude Code

AGENTS.md — set up KHMS memory for yourself, in one pass

You are an agent that has been told: "set up your memory per this repo." This file is the whole job. Work top to bottom. Everything you need is in this repository; nothing here needs network access, a database, or a service.

Before you start, know the two rules that outrank convenience:

1. You may not write into memory/know/ without your operator's approval. Background stages propose; approval is a separate, human-or-strong-model step. This is what keeps a fabricated card from becoming a remembered fact.
2. Cards are immutable once approved. You will be tempted to "just fix" one. Don't. Write a new card that supersedes it. The wrong old card is evidence about how you were wrong.

---

Step 1 — Decide where memory lives, and set KHMS_ROOT

Pick a directory outside the code you work on — memory outlives any one project. Everything below is relative to it. Every script in tools/ reads the environment variable KHMS_ROOT and falls back to its own parent directory, so a copied tools/ directory works with no edits.

export KHMS_ROOT="$HOME/.agent-memory"      # put this in your shell profile too

Create the layout and copy the tooling:

git clone <this-repo> /tmp/khms && /tmp/khms/tools/khms_init.sh "$KHMS_ROOT"

khms_init.sh is idempotent: it creates the directories, the ID counter, an empty tag registry, and copies tools/ and tools/prompts/ into $KHMS_ROOT. It writes nothing into memory/know/.

Decide now how the base is versioned, and write the choice down. Two options, and they are not equivalent:

• A git repository. git init inside $KHMS_ROOT, commit after every approval. You get history, log -p on a single card, bisect, blame, and a remote you can clone. This is the default and the better answer whenever it is allowed.
• Hardlinked snapshots — tools/khms_snapshot.sh, for a base that must not be in a repository at all (some operators want their knowledge only on their own machine and their own synced folder, with no remote and no clonable history). --tag is the commit, --list the log, --diff the status, --restore the checkout, --prune the retention policy; unchanged files are hardlinks, so a daily snapshot of a large base costs the bytes that actually changed, and every snapshot is a complete tree you can read with cat. What you do NOT get: bisect, blame, per-file history, or a remote. Run it from cron before the nightly and after the morning review, and keep the snapshot root OUTSIDE the base — inside, a synced folder would carry every snapshot too.