# memory commands

The fourteen memory slash commands, registered once by the memory component through `register.ts` (`registerMemoryCommands(pi, deps)`). `MEMORY_COMMAND_NAMES`: `/memory /memfs /remember /init /doctor /recompile /memory-repository /sleeptime /reflect /dream /search /people /facts /agreements`. Score ~24 (53 files, DI surface, central registration).

## Anatomy

| Path | Purpose |
|------|---------|
| `register.ts` | Central registrar and the ONLY place command names are declared. |
| `metadata.ts` / `runtime.ts` / `runtime-loader.ts` | Lazy command handlers (#10860). `metadata.ts` holds the name, description and argument hint of the eleven commands whose handlers ship in the `#omo-memory-commands-runtime` sidecar (`extensions/omo-memory-commands.js`); `register.ts` registers them from it synchronously and each command module spreads the same entry. `runtime.ts` (sidecar entry) runs a command module's own registrar against a capturing `MemoryCommandPort` (`registerCommand` plus `sendUserMessage` forwarded to the real API) and caches the handler per API and deps. `runtime-loader.ts` is the shared once-per-process import; a failed load is not cached and answers an actionable error. Nothing in the entry bundle may import `runtime.ts` or a lazy command module statically. |
| `types.ts` | `MemoryCommandDeps` / `MemoryCommandContext` / identity seams: `respond` notifications, repo access, interactivity, process liveness. |
| `args.ts` | Shared `parseCommandArgs` flag/positional parsing. |
| `backup.ts` / `repo.ts` | Repository backup and git/repository access helpers. |
| `memory.ts` / `memfs.ts` + `memfs-runtime.ts` + `memfs-shared.ts` / `memfs-extra.ts` | `/memory` status; `/memfs` file tree. `/memfs` registers synchronously and lazy-loads its runtime on first invocation; replacement is noninteractive and ALWAYS backs up first. |
| `memory-unlock.ts` | `/memory unlock <lock> [--force]`: the way out of a kept stranded git lock (memory-core `inspectStrandedGitLock` / `unlockStrandedGitLock`). Shows the findings, REFUSES while any live holder, repository user or memory writer is visible (forced or not), otherwise removes only that lock after the confirm dialog; noninteractive needs `--force`, which skips the prompt only. The removal re-inspects immediately before the unlink and keeps a lock whose inode or mtime changed. |
| `init.ts` | `/init` - NEVER overwrites an existing memory repository. |
| `doctor.ts` / `doctor-runtime.ts` / `doctor-checks.ts` / `doctor-reservation.ts` | Synchronous command registration with a first-invocation lazy runtime; health checks; the `facts` line stays silent at zero state. `doctor-reservation` warns on a ghost `active.lock` (dead/missing launcher identity) with reclaim remediation. |
| `recompile.ts` / `remember.ts` / `search.ts` / `sleeptime.ts` / `reflect.ts` / `dream.ts` + `dream-staging.ts` | Single-purpose commands; `/sleeptime` shows the resolved nudge/facts/dream/people/soul settings. |
| `memory-repository.ts` | Push-only git mirror sync (the cloud-free sync story). |
| `people.ts` / `people-runtime.ts` / `people-ask.ts` / `people-query.ts` / `people-render.ts` / `people-search.ts` + `people.test-support.ts` | People cards: query/selection, ask runner (`createPeopleAskRunner`), roster/card rendering, search hits. `people.ts` is only the registration shell; `runPeopleCommand` in `people-runtime.ts` ships in the memory palace sidecar (`../palace/runtime.ts`) and loads on the first `/people`. |
| `agreements.ts` | `/agreements [list] \| add [--project] <text> \| ack <id> \| drop <id>`: the person's own surface over `system/agreements.md` and the ONLY writer of `by: human` items (commits with `Omo-Writer: human-command`, then busts the prompt cache). |
| `facts.ts` / `facts-status.ts` | `/facts` queue depth, parked/backoff counts, next eligibility, bounded per-conversation last-failure list. Corrupt `failures.json` renders as UNREADABLE, never as zeros. `/facts retry [--conversation <id>]` is the ONLY unpark path: clears failure records and fires one reconcile/launch; never moves queue data or either watermark. |
| `skill-frontmatter.ts` / `tokens.ts` | Skill-name frontmatter repair; token estimates (`estimateSystemTokens`). |
| `commands.test-support.ts` | Shared fixtures. |

## Conventions

- Handlers return `Promise<string>` command output; user notifications go only through the injected `respond` seam.
- Read-only command output never enters model context.
- Commands are centrally registered, not auto-discovered: adding one means `register.ts` + `MEMORY_COMMAND_NAMES` + a colocated test.
- Tests use deterministic fixtures, temporary repositories, and `#given/#when/#then` names.

## Commands

```bash
bun test packages/omo-senpi/src/components/memory/commands
tsgo --noEmit -p packages/omo-senpi/tsconfig.json
```