AGENTS.md git:20261010.6005960A

Immutable. This exact content never changes and is served at /api/v1/blob/ec62d3797e91c0fb.

# AGENTS.md - Hippo

## Project
- `hippo-memory`, a TypeScript memory system and CLI with UI, integrations, benchmarks, and evaluation harnesses.
- Read `README.md`, `PLAN.md`, `ROADMAP.md`, and relevant docs before broad product or architecture changes.
- Work plane boundary: `docs/plans/2026-09-12-work-plane-boundary.md` (ROADMAP Part VII, Track W, W0).

## Commands
```bash
npm run build
npm test
npm run test:eval   # the eight slow token-eval harness tests, which npm test skips; --project codex runs the four Codex ones
npm run build:ui
npm run build:all
npm run smoke:pack
npm run smoke:openclaw-install
```

## Rules
- Preserve public CLI and package APIs unless the user asks for a breaking change.
- Document public APIs with JSDoc.
- Prefer focused tests in `tests/` or nearby integration/eval harnesses before changing memory behavior.
- Name a new test file after the behaviour it pins, not the ticket (`store-stats-concurrency.test.ts`, not `a7-t3.test.ts`). Seed test stores through `initStore`, `createMemory` and `writeEntry`; write raw SQL only when the test is about SQL.
- A new test file needs a contract with no owner file: find the owner and add a row first.
- One owner per contract at the strongest boundary, with one wire-up row per other transport; a test written to carry a refactor is deleted by the PR that lands it.
- No production export for a test; seed helpers live in `tests/_helpers`.
- Do not commit generated `dist/` or UI build output unless the repo expects it for a release.
- A PR's changelog entry goes in its own `changelog.d/<branch-with-dashes>.md`, never in `CHANGELOG.md`; the release commit folds them in (`changelog.d/README.md`).
- CI fails when any oxlint rule's hit count rises above `.oxlint-baseline.json`. Fix new hits in the files you touch; after clearing old ones, `node scripts/check-lint-ratchet.mjs --update` and commit the lower baseline.
- Comments say why, in one line. Ticket codes, versions, reviewer notes and dates go to docs or the git log; CI fails when a file's count of them rises above `.comment-history-baseline.json`. After rewriting old ones, `node scripts/check-comment-history.mjs --update` and commit the lower baseline.
- No `src/` file over 800 lines and no function over 80. CI fails when a new one appears or one in `.size-baseline.json` grows; after shrinking old ones, `node scripts/check-size-ratchet.mjs --update` and commit the lower baseline.
- An eval that reads host transcripts (`~/.claude/projects/*.jsonl`) copies its corpus outside the repo at registration and names the copy in the prereg: Claude Code deletes sessions after 30 days by default, so a live-path corpus cannot be re-run.
- Use Hippo memory commands when useful, but do not store secrets.
- The `compactions` table is one record per Claude Code compaction, not a memory row: recall, FTS, context and sleep's memory passes never read it. Memories saved from a compaction carry the `compaction-memory` tag and a `compaction:` source and fade like any other memory; a restated item is skipped, and another session's restatement strengthens the row it repeats. The keep rule (`KEEP_PAIRS` in `src/core/memory.ts`) covers imported agent memories only and needs tag and source both; `canAutoDelete` and `AUTO_DELETABLE_SQL` (`src/store/rule-sql.ts`) must change together. No automatic pass (sleep, dedupe, audit) deletes a memory that backs an object: `AUTOMATIC_DELETE_SQL` in `src/store/delete-and-batch.ts` checks every table in `MEMORY_BACKED_TABLES`.

## Never Do
- Never store secrets, API keys, tokens, raw private emails, or sensitive personal data in Hippo memories.
- Never break the public `hippo` CLI command names without a migration path.
- Never auto-graduate long-term lessons without evidence and rationale.
- Never delete memory history when archiving or weakening would preserve recoverability.
- Never ship release changes without `npm run build:all`.

<!-- hippo:start -->
## Project Memory (Hippo)

At the start of every task, run:
```bash
hippo context --auto --budget 1500
```
Read the output before writing any code.

On errors or unexpected behaviour, record it right then, while you work,
never as a closing step:
```bash
hippo remember "<description of what went wrong>" --error
```

When you learn something that should outlive this session (a decision and
its reason, a user preference, a lesson), record it right then, while you
work, never as a closing step. Leave out secrets and personal details:
```bash
hippo remember "<what you learned and why>"
```

When Hippo's Codex wrapper is installed, session-end capture runs automatically.
If the wrapper is not installed, capture a brief summary manually:
```bash
hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
```
<!-- hippo:end -->