AGENTS.md

1# memory-core - Harness-Neutral Agent Memory Engine
2 
3## OVERVIEW
4 
5`@oh-my-opencode/memory-core` owns the shared memory domain used by harness
6adapters: a git-backed markdown MemFS, atomic memory tools, prompt compilation,
7reflection scheduling, transcript search, synchronization, and seed content.
8The public API is the barrel at `src/index.ts`.
9 
10## ANATOMY
11 
12| Directory | Responsibility |
13|-----------|----------------|
14| `src/git/` | Git command boundary, clean-tree checks, commits, merges, remotes, and typed git errors. |
15| `src/identity/` | Memory identity resolution and the `OMO_MEMORY_HOME` directory layout. |
16| `src/locks/` | Cross-process locks for memory writes, reflection scheduling, and transcript state. |
17| `src/memfs/` | Memory-path validation, markdown frontmatter parsing, and hook-script installation. |
18| `src/tools/` | `memory` and `memory_apply_patch` operations, patch parsing, typed tool errors, and auto-commit behavior. |
19| `src/journal/` | Per-conversation transcript cursors, reflection snapshots, and durable journal state. |
20| `src/reflection/` | Trigger evaluation, run reservation, worktree execution, completion validation, and merge outcomes. |
21| `src/compile/` | Compile committed memory revisions into marked system-prompt blocks and cache them by template hash. |
22| `src/search/` | Query parsing, transcript providers, and ranked memory/session search. |
23| `src/sync/` | Remote mirror synchronization and secret redaction. |
24| `src/reminders/` | Reflection and memory-maintenance reminder generation. |
25| `src/seeds/` | Default memory blocks and first-run repository seeding. |
26| `src/concurrency/` | Subprocess fixtures for lock and multi-writer tests; not a public runtime module. |
27 
28## CORE INVARIANTS
29 
30- **Stay harness-neutral.** Production code and package dependencies must not
31  import Senpi, Pi, OpenCode adapters, or other harness-specific packages.
32  `src/harness-neutrality.test.ts` enforces this boundary.
33- **Treat the memory repository as transactional state.** Write tools acquire
34  the `memory-write` lock, require a clean repository, validate paths, apply one
35  operation, and commit only the affected paths. Do not bypass
36  `GitMemoryRepo`, lock domains, or the tool entry points.
37- **Compile from committed state.** Prompt compilation may target `HEAD` or an
38  explicit revision. Uncommitted working-tree content is not authoritative
39  memory.
40- **Preserve markdown contracts.** Memory files require YAML frontmatter with a
41  non-empty `description`; `read_only: "true"` blocks mutation. Keep UTF-8,
42  normalized repository-relative paths, and LF output.
43- **Keep reflection transitions deterministic.** Manual triggers outrank
44  compaction, which outranks step-count triggers. Only one active run and one
45  merged pending reservation may exist.
46- **Keep locks domain-specific.** Use `memory-write`,
47  `reflection-scheduler`, or the transcript-specific lock. Do not replace them
48  with one global lock or add timing-based tests.
49- **Redact before external synchronization.** Remote mirror output must pass
50  through the sync redaction layer; never copy secret-bearing raw logs or
51  configuration into committed memory.
52 
53## PUBLIC SURFACES
54 
55- `runMemoryTool()` implements `create`, `str_replace`, `insert`, `delete`,
56  `rename`, and `update_description`.
57- `runMemoryApplyPatch()` applies multi-file Codex-style patches inside the
58  memory repository.
59- `GitMemoryRepo` owns repository initialization, clean checks, commits,
60  revisions, merge worktrees, and remote detection.
61- `evaluateTransitions()`, `reserveTransition()`, and
62  `completeTransition()` form the pure reflection state machine.
63- `compileMemoryBlock()` and `compileMemoryBlockAtRevision()` render the
64  committed memory projection injected into a harness prompt.
65 
66## CONSUMERS
67 
68Harness adapters provide identity, lifecycle events, tool registration, and
69sync orchestration. The Senpi adapter lives under
70`packages/omo-senpi/src/components/memory/`; keep adapter-specific behavior
71there rather than importing it back into this package.
72 
73## QA
74 
75```bash
76bun test packages/memory-core/src/
77bun run --cwd packages/memory-core typecheck
78```
79 
80For a focused change, run the nearest co-located `*.test.ts` first, then the
81package suite. Concurrency tests must await exact state or process events with
82bounded timeouts; never add fixed sleeps or retry loops.
83 
84## ANTI-PATTERNS
85 
86- Importing a harness package into `memory-core`.
87- Writing directly to memory markdown without path validation, frontmatter
88  parsing, locking, and an atomic git commit.
89- Reading the dirty worktree as compiled memory.
90- Mutating `read_only` blocks or accepting non-UTF-8 memory files.
91- Swallowing git, lock, merge, or reflection failures.
92- Testing cross-process behavior with timing luck.
93