Project memory

KHAELOR maintains its own memory of your project — and unlike free-form notes, every entry is anchored to the exact session and event that produced it.

The life cycle#

1. Write — when the agent discovers a durable fact (a convention, a build command, a pitfall) it calls the lightweight remember tool. Auto-approved: writing to .khaelor/MEMORY.md is allowed in every phase, because remembering IS understanding.
2. Read — the file is injected into the instruction tier at every session start, alongside KHAELOR.md/CLAUDE.md.
3. Audit — /memory lists entries with their provenance.
4. Hygiene — low-confidence entries not re-confirmed surface as purge candidates at the next /compact.

The format#

# Project memory

## Conventions
- Errors flow through Result<T, KError>; never throw in src/core.
  <!-- khaelor: session=01J8K2… tool=toolu_01… confidence=high date=2026-08-10 -->

## Commands
- Full build: npm run check (includes the mandatory header check).
  <!-- khaelor: session=01J8K2… tool=toolu_02… confidence=high date=2026-08-10 -->

## Pitfalls
- src/tui/render.ts: never touch the buffer outside the 16ms tick — tearing.
  <!-- khaelor: session=01J8F1… tool=toolu_09… confidence=medium date=2026-08-09 -->

Readable, hand-editable, git-versionable. The provenance comment is the differentiator: the tool id links to a durable tool.requested event in the referenced session's JSONL — you can open the log and see exactly what the agent had just observed when it decided to remember.

The remember tool#

Each write also emits a durable memory.written event in the current session — memory changes are themselves part of the auditable history.

Versus free-form memory files#

Plain markdown memories rot: you find a claim and cannot tell when it was true or what justified it. KHAELOR's memories always answer three questions — who wrote this (which session), based on what (which event), how sure was it (confidence) — and the hygiene loop retires what stops being confirmed.