khms-memory AGENTS.md

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/.

Resulting layout — memorize it, you will refer to it constantly:

$KHMS_ROOT/
  MEMORY.md                 generated index; keep this in your context always (≤80 lines)
  memory/know/K-*.md        the cards — one claim per file, immutable
  memory/views/             generated: topics/<tag>.md, by-type/<type>.md, tags.md, recent.md
  memory/inbox/             proposals awaiting review (temp labels, no IDs yet)
  memory/inbox/.staging/    what each pipeline stage was actually handed (forensics)
  memory/archive/know/      superseded and condensed cards — "fog", still greppable
  journal/YYYY-MM-DD.md     what happened today, written as it happens
  tools/                    the scripts below; tools/.next_id is the ID counter