pi-obsidian-memory 0.0.1 → 0.1.1

package/README.md

@@ -1,15 +1,245 @@
 # pi-obsidian-memory
 
-Memória de longo prazo para o [pi coding agent](https://pi.dev), gravada em vaults do [Obsidian](https://obsidian.md). O OneDrive é opcional.
+Long-term memory for the [pi coding agent](https://pi.dev), stored as Markdown notes in
+[Obsidian](https://obsidian.md) vaults.
 
-> **Status:** em especificação (fase F0). Ainda não há código utilizável: esta versão só reserva o nome no npm.
+pi forgets everything when a session ends. With this package it keeps what matters (your preferences, the rules and
+decisions of each project, lessons from past mistakes) and brings it back when it helps. You can read and edit every
+note in Obsidian.
 
-- Um vault **global**, com os aprendizados sobre o usuário, e um vault **por projeto**.
-- Notas nativas do Obsidian, com índice e templates: só aprendizados e pontos importantes.
-- Tudo configurável, com onboarding (`/memory-setup` e `/memory-init`).
+## Contents
 
-Documentação do projeto em [`docs/`](docs/). Decisões em [`docs/OPEN-QUESTIONS.md`](docs/OPEN-QUESTIONS.md).
+1. [Requirements](#requirements)
+2. [Install](#install)
+3. [Set up](#set-up)
+4. [How it works](#how-it-works)
+5. [Settings](#settings)
+6. [Where things are stored](#where-things-are-stored)
+7. [Privacy](#privacy)
+8. [Troubleshooting](#troubleshooting)
+9. [Known limits](#known-limits)
+10. [Development](#development)
 
-## Licença
+## Requirements
+
+| What | Why | Required? |
+|---|---|---|
+| [pi](https://pi.dev) | Runs the package. Tested with pi 1.3.0. | Yes |
+| Node 22.19 or later | pi runs the package on it. | Yes |
+| A chat model configured in pi | Saves notes in the background (capture) and finds notes for each message (memory agent). Any model pi can use works; a small, cheap one is enough for the memory agent. | Yes |
+| A TypeSafe API key (`TYPESAFE_API_KEY`) | Jev, TypeSafe's classifier, decides which notes help each message and checks shell commands (see [Guards](#guards)). Get a key at [typesafe.ai](https://docs.typesafe.ai). Price: $0.042 per million input tokens. | Strongly recommended |
+| [Obsidian](https://obsidian.md) | Reading and editing the notes. | No: notes are plain Markdown |
+
+**Without `TYPESAFE_API_KEY`:** no notes are added to your messages (pi tells you once per session), and every
+`bash` or `powershell` call is refused, because the shell-edit guard cannot check it.
+
+### Setting the TypeSafe key
+
+Set the environment variable before starting pi:
+
+```bash
+# macOS / Linux (add it to ~/.bashrc or ~/.zshrc to keep it)
+export TYPESAFE_API_KEY=your-key
+```
+
+```powershell
+# Windows (kept for new terminals)
+setx TYPESAFE_API_KEY "your-key"
+```
+
+The key can also be pi's stored credential for the `typesafe` provider. It is never written to this package's config.
+
+## Install
+
+```bash
+pi install npm:pi-obsidian-memory
+```
+
+Then restart pi. To try it for one run without installing: `pi -e npm:pi-obsidian-memory`.
+
+`pi list` shows installed packages; `pi update` updates them.
+
+## Set up
+
+1. **Create the global vault.** Run `/memory-setup` in pi. It asks:
+   - where the global vault goes: a new folder, or an existing folder (an Obsidian vault you already have works);
+   - which chat model saves memory (capture); the model in use is the default;
+   - which chat model runs the memory agent; the list is sorted by price, cheapest first.
+
+   It shows what each choice sends where, then writes the config and the vault.
+2. **Give each project its own vault.** Open pi in the project folder and run `/memory-init`. A folder without a
+   project vault uses the global vault only.
+3. **Use pi as usual.** Say "remember that …" to save something. The rest happens on its own.
+
+Run `/memory-setup` again at any time to open the settings screen. Both commands need pi's interactive mode.
+
+## How it works
+
+### Two vaults
+
+- **Global vault:** about you. How to address you, your preferences, your patterns, lessons that apply everywhere.
+- **Project vault:** about one project. Its rules, decisions, facts, open issues.
+
+Each note holds one point. Its file name is the statement (for example `pnpm/Use pnpm, never npm.md`), the body has
+the detail, and the frontmatter says what kind of memory it is:
+
+```markdown
+---
+id: 01JABCDE7XKQ2M9V3RTN8WPZ5F
+type: rule
+created: 2026-10-04
+updated: 2026-10-04
+dontForget: true
+---
+
+Use pnpm for every install and script. In CI: `pnpm install --frozen-lockfile`.
+```
+
+Types: `rule`, `procedure`, `constraint`, `fact`, `issue`, `question`, `decision`, `lesson`, `goal`, `risk`, `idea`,
+`reference`. Notes are written in English. They are never deleted: a retired note moves to `archive/`. The full format
+is in [docs/vault-format.md](docs/vault-format.md).
+
+### What happens during a session
+
+1. **Session start.** Every note marked `dontForget: true` is loaded into pi's system prompt, in full.
+2. **Each message.** Jev decides whether stored memory would help. If yes, the memory agent searches and reads the
+   vaults, Jev scores each note it found, and the notes that help are added after your message, within
+   `context.budgetChars` (12,000 characters by default). A note you changed since it was loaded is sent again.
+3. **In the background (capture).** Every 10 assistant turns or 15 tool calls, once the session has at least three of
+   your messages, a review reads the new part of the conversation and saves, updates, archives or replaces notes. What
+   was not reviewed yet is also saved before pi compacts the session and when it ends. Capture never asks you
+   anything: what it is unsure of is not saved. The cadence follows
+   [pi-hermes-memory](https://github.com/chandra447/pi-hermes-memory).
+
+You change notes in Obsidian whenever you want. pi must read a note before changing it, and a note you edited since
+then is never overwritten.
+
+### Tools the agent uses
+
+| Tool | Does |
+|---|---|
+| `memory_search` | Finds notes by words and by meaning, in the global vault, the project vault or both |
+| `memory_get` | Reads a note, a folder's index, or anything under `archive/` |
+| `memory_add` | Saves a new note |
+| `memory_update` | Changes a note |
+| `memory_archive` | Moves a note to `archive/` |
+| `memory_succeed` | Replaces a note with a new one; both link to each other |
+
+The bundled skill `obsidian-memory` teaches the agent where notes go and how to use these tools.
+
+### Commands
+
+| Command | Does |
+|---|---|
+| `/memory-setup` | First setup; afterwards, the settings screen |
+| `/memory-init` | Gives the current project its own vault |
+| `/memory-doctor` | Checks the vaults, the config, the models and the keys, and says what is wrong |
+| `/memory-export` | Saves both vaults to a new `.zip` |
+
+### Guards
+
+- **Vault guard.** The agent reaches the vaults only through the memory tools. pi's file tools (`read`, `write`,
+  `edit`, `grep`, `find`, `ls`) on a vault are refused, and so are shell commands that write a vault path out. You and
+  Obsidian are not affected.
+- **Shell-edit guard.** Before every `bash` or `powershell` call, Jev checks whether the command edits a file: a
+  redirect, an in-place edit, inline code, a script that writes, a copy or download that creates a file, or a
+  hardlink. If so, the call is refused and the agent is told to use `edit` or `write`. When Jev cannot answer, the
+  call is refused.
+
+### Dashboard
+
+Each vault gets a `Memory.base` file: an Obsidian view of all notes, the Don't forget notes and the archive. Your edits
+to it are kept.
+
+## Settings
+
+All settings are changed in the `/memory-setup` screen, or by asking pi. You never need to edit the file.
+
+| Setting | Default | What it does |
+|---|---|---|
+| Global vault | chosen at setup | Folder of the global vault |
+| Projects | none | Each project folder and its vault, added by `/memory-init` |
+| Capture model | the model in use at setup | Chat model that saves memory |
+| Memory agent model | chosen at setup | Chat model that searches and reads notes for each message |
+| `capture.nudgeInterval` | 10 | Assistant turns between background reviews |
+| `capture.nudgeToolCalls` | 15 | Tool calls between background reviews |
+| `capture.flushMinTurns` | 6 | Your messages a session needs before it is saved at compaction or at the end |
+| `capture.reviewEnabled` | on | Background review during the session |
+| `capture.flushOnCompact` | on | Save before pi compacts the session |
+| `capture.flushOnShutdown` | on | Save when the session ends |
+| `context.budgetChars` | 12,000 | Characters of relevant notes added at session start and to each message (Don't forget notes do not count) |
+| `limits.maxStatementChars` | 100 | Longest note name |
+| `limits.maxBodyChars` | 1,000 | Longest note body |
+| `limits.maxNotesPerFolder` | 20 | `/memory-doctor` suggests splitting a folder above this |
+| Embeddings | local | Model for search by meaning: local (no key), OpenAI (`OPENAI_API_KEY`) or Google (`GEMINI_API_KEY`) |
+| Decision model | Jev | Jev (TypeSafe, cutoffs 0.5/0.5) or Laya (local server, you set the cutoffs) |
+
+Every field, the file format and running Laya locally are in [docs/config.md](docs/config.md).
+
+## Where things are stored
+
+| What | Where |
+|---|---|
+| Notes | The vault folders you chose |
+| Settings | `pi-obsidian-memory/config.json` in pi's agent folder (`~/.pi/agent` by default) |
+| Search index | `pi-obsidian-memory/index/` in pi's agent folder; rebuilt from the notes when needed |
+| Local search model | `pi-obsidian-memory/models/` in pi's agent folder; downloaded once, about 135 MB |
+
+The vaults hold only notes, their `index.md` files, `_templates/` and `Memory.base`, so they can live in any synced
+folder (OneDrive, iCloud, Dropbox).
+
+## Privacy
+
+- Capture and the memory agent send conversation and note content to the chat models you choose.
+- Jev sends your messages, candidate notes and shell commands to TypeSafe.
+- Search by meaning runs on your machine by default; OpenAI or Google receive note content and queries only if you
+  choose them.
+- `/memory-setup` shows each of these before it saves.
+- Notes are saved as written, without masking. The config file never holds a key.
+
+## Troubleshooting
+
+Run `/memory-doctor` first: it checks the vaults, the config, the models and the keys, and says what is wrong. The only
+thing it offers to change is a blank note, after asking you.
+
+| You see | Do |
+|---|---|
+| "Memory is off" or "Run /memory-setup first" | Run `/memory-setup` |
+| "No chat model is available" during setup | Connect a model in pi (`/login`), then run `/memory-setup` again |
+| No relevant notes are ever added | Check that `TYPESAFE_API_KEY` is set, then run `/memory-doctor` |
+| "Refused: the shell-edit guard could not check this command" | Same: the shell-edit guard needs Jev |
+| "Memory capture did not finish: …" | The text after the colon names the cause, for example a model without a key |
+| `No API key found for "<provider>"` in `/memory-doctor` | Log in to that provider in pi (`/login`) or set its key |
+
+## Known limits
+
+- Paths are compared ignoring case on Windows and macOS and with case on Linux, whatever the volume.
+- The vault guard does not see a vault path the shell builds indirectly (variables, globs, scripts), tools of other
+  extensions, or foreground subagents.
+- How well capture judges what to save is not yet measured against a real model.
+
+## Development
+
+```bash
+npm install
+npm run lint
+npm run typecheck
+npm test              # offline: pure tests and tests on a real temporary disk
+npm run test:e2e      # the real pi over RPC, through OmniRoute
+npm run test:model    # live tests: real models and network
+pi -e ./src/pi/extension.ts
+```
+
+`npm run test:e2e` runs one test per feature with the real `cc/claude-haiku-5-5` through OmniRoute
+(`pi-omniroute-sync`) and the real Jev. It reads `OMNIROUTE_URL`, `OMNIROUTE_API_KEY` and `TYPESAFE_API_KEY` from the
+environment. CI runs it on Windows, and lint, typecheck and `npm test` on Windows, macOS and Linux.
+
+Releases are automatic: a push to `main` with a `feat` or `fix` commit bumps the version, rewrites `CHANGELOG.md`,
+publishes to npm and creates the GitHub release.
+
+More: [vision](docs/VISION.md), [roadmap](docs/ROADMAP.md), [note format](docs/vault-format.md),
+[settings](docs/config.md).
+
+## License
 
 [MIT](LICENSE)

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "pi-obsidian-memory",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "Long-term memory for the pi coding agent, stored in Obsidian vaults",
   "keywords": [
     "pi",
     "pi-coding-agent",
+    "pi-package",
     "obsidian",
     "memory",
     "agent-memory"
@@ -20,24 +21,53 @@
     "url": "https://github.com/DavyMassoneto/pi-obsidian-memory/issues"
   },
   "type": "module",
+  "imports": {
+    "#src/*": "./src/*/index.ts",
+    "#test-helpers": "./tests/helpers/index.ts"
+  },
   "engines": {
-    "node": ">=24"
+    "node": ">=22.19.0"
   },
   "files": [
-    "CHANGELOG.md"
+    "src",
+    "skills"
   ],
   "scripts": {
-    "release": "node scripts/release/cli.ts",
-    "test": "vitest run",
+    "format": "biome check --write .",
+    "lint": "biome check .",
+    "test": "vitest run --project unit",
+    "test:model": "vitest run --project model",
+    "test:e2e": "vitest run --project e2e",
     "typecheck": "tsc --noEmit"
   },
-  "publishConfig": {
-    "access": "public"
+  "pi": {
+    "extensions": [
+      "./src/pi/extension.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
   },
   "devDependencies": {
-    "@types/node": "^24.13.6",
-    "git-cliff": "^2.14.2",
-    "typescript": "^7.0.2",
-    "vitest": "^5.0.1"
+    "@biomejs/biome": "2.5.15",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@types/node": "24.19.1",
+    "@types/stopword": "2.0.3",
+    "git-cliff": "2.14.2",
+    "pi-omniroute-sync": "1.2.1",
+    "typebox": "1.3.27",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "4.3.1",
+    "fflate": "0.8.3",
+    "stopword": "3.1.5",
+    "ulid": "3.0.2",
+    "yaml": "2.9.1"
   }
 }

package/skills/obsidian-memory/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: obsidian-memory
+description: How to use the Obsidian long-term memory (global and project vaults) - where notes go, note types, what is not memory, and the memory tools. Load before searching or reading memory, before saving something the user asked to remember, or when a memory block appears in the context.
+---
+
+# Obsidian memory
+
+Long-term memory lives in Obsidian vaults. Notes are in English, whatever language the user speaks.
+
+## Two layers
+
+- Global vault: about the user (how to address them, preferences, patterns, global lessons).
+- Project vault: everything else about the current project.
+- Classify each memory. When unsure which vault, ask the user.
+- A folder with no registered project has the global vault only.
+
+## Layout and placement
+
+- One folder per subject. Each folder holds short notes, one point per note. Subjects nest with no depth limit.
+- Place a note from general to specific: `typescript/testing/`, not `testing/typescript/`.
+- Reuse before creating: walk the existing tree (read folder indexes level by level) and use the path that already covers the subject.
+- When two paths fit, ask the user.
+- Every folder has an `index.md` listing its subfolders and its notes (type and don't forget mark). The system keeps it up to date; never write it by hand.
+- Not subjects: hidden folders, and at the vault root `archive/` and `_templates/`.
+- `index` (any case) is reserved: no note can use it as its statement.
+
+## Notes
+
+- The file name is the statement: reading the name tells exactly what the note says. The body holds the detail.
+- Keep notes short, one point each. A new point in the same subject is a new note in that folder.
+- Name: at most 100 characters by default. It must be a valid Windows file name and must not contain `< > : " / \ | ? * [ ] # ^`, control characters, a leading or trailing space, or a trailing dot. No Windows reserved names (`CON`, `NUL`, `COM1`...).
+- Body: never empty, at most 1,000 characters by default. Record the detail even when the name says it all.
+- An invalid note is refused with every reason. Rewrite it or split it into smaller notes.
+- A note can be marked Don't forget: it is loaded in full at session start.
+
+## Types
+
+Pick exactly one. The list is closed. When unsure which type fits, ask the user.
+
+- `rule`: how to do things; a user preference or a project convention.
+- `procedure`: steps to do something in this project.
+- `constraint`: a limit imposed from outside (platform, deadline, client).
+- `fact`: how things are, about the user or the project.
+- `issue`: a known problem that is still open, with its workaround.
+- `question`: something still undecided or unknown.
+- `decision`: a choice that was made, with its why.
+- `lesson`: something learned from a mistake or a bug.
+- `goal`: a committed objective for the future.
+- `risk`: a problem that may happen.
+- `idea`: a possibility not committed to yet.
+- `reference`: where to find something external.
+
+## Not memory
+
+- Tasks and TODOs.
+- Session logs.
+- Anything the code or git history already records.
+
+Secrets (keys, passwords, tokens) are memory: the vault is the user's own safe. Save them like any other note, with no masking. When unsure whether something is memory at all, ask the user.
+
+## Reading
+
+The memory block at session start, and the relevant notes added to a message, are only part of the memory. A note added again as replacing an earlier copy supersedes it; a note marked no longer valid must not be relied on. Search and read more when you need it.
+
+- `memory_search`: search by words and, when semantic search is on, by meaning, over one or both vaults. When it says semantic search is off, try other words too. Each result gives the vault, the path, the type, the Don't forget mark and whether the note needs fixing. Archived notes and notes with invalid frontmatter are not searched.
+- `memory_get`: takes a vault and a path.
+  - A note path returns the note in full, with every problem if it breaks any rule.
+  - A folder path returns its index. `""` is the vault root.
+  - Paths under `archive/` can be read.
+- To place a note, read the root index and walk down the folder indexes with `memory_get`.
+
+## Saving
+
+- Memory is captured, updated and retired automatically by a background review of the conversation; you don't need to save anything for it.
+- Use `memory_add` only when the user explicitly asks you to remember something. Never save on your own initiative, and never nudge the user to save.
+- Choose the vault, the folder and the type as described above. Ask when unsure.
+- A name already taken (in any case) is refused with the existing note. If it is the same point, read it with `memory_get` and, only if the user asked for a change, use `memory_update`; otherwise choose a statement that says what is new.
+- Do not save skills or instructions to a vault. Vaults hold only memory.
+
+## Changing and retiring
+
+Use these only when the user explicitly asks. Always read the note with `memory_get` in this session first, with the exact vault and path; a note not read, or changed on disk since it was read, is refused.
+
+- `memory_update`: changes the body, type or Don't forget mark of a note. It never renames: a different statement is a new note that replaces the old one.
+- `memory_archive`: retires a note that stopped being true and has no successor. It moves to `archive/`; nothing is ever deleted.
+- `memory_succeed`: replaces a note with a new one (new statement, folder, type and body). The old note moves to `archive/` and both are linked.
+- Notes under `archive/` cannot be changed.
+- After a partial result, do not call again: tell the user what was done and ask them to check the vault.
+
+## Vault access
+
+- Never read or write vault files with file tools (`read`, `write`, `edit`, `grep`, `find`, `ls`) or with the shell, however the path is reached.
+- Use only the memory tools. Files outside the vaults are unaffected.
+- The user edits the vault freely in Obsidian; a note can change between sessions.
+
+## Setup
+
+- With no global vault registered there is no memory: tell the user to run `/memory-setup`.
+- A folder not registered as a project has global memory only: the user can run `/memory-init` to register it.
+- Notes listed under Needs fixing, blank notes and duplicate ids: suggest the user run `/memory-doctor`.
+- A copy of the memory as a zip: the user can run `/memory-export`.

package/src/domain/capture/constants.ts

@@ -0,0 +1,5 @@
+import type { CaptureTally } from "./types.ts"
+
+export const MIN_USER_MESSAGES_BEFORE_REVIEW = 3
+
+export const EMPTY_TALLY: CaptureTally = { userMessages: 0, turnsSinceReview: 0, toolCallsSinceReview: 0 }

package/src/domain/capture/index.ts

@@ -0,0 +1,6 @@
+export * from "./constants.ts"
+export * from "./input-problems.ts"
+export * from "./schemas.ts"
+export * from "./tally.ts"
+export * from "./types.ts"
+export * from "./validate.ts"

package/src/domain/capture/input-problems.ts

@@ -0,0 +1,9 @@
+import { Value } from "typebox/value"
+
+import { describeSchemaErrors } from "#src/domain/validation"
+import { CaptureInputSchema } from "./schemas.ts"
+import type { CaptureInput } from "./types.ts"
+
+export function captureInputProblems(input: CaptureInput): string[] {
+  return describeSchemaErrors(Value.Errors(CaptureInputSchema, input), "capture input")
+}

package/src/domain/capture/schemas.ts

@@ -0,0 +1,92 @@
+import Type from "typebox"
+
+import {
+  AgentContextSchema,
+  HashSchema,
+  ObservationSchema,
+  PathSchema,
+  ReadActionSchema,
+  ReadObservationSchema,
+  TextSchema,
+  VaultSchema,
+} from "#src/domain/memory-agent"
+import { NoteIdSchema, NoteTypeSchema } from "#src/domain/note"
+
+export const CaptureDraftSchema = Type.Object(
+  { folder: PathSchema, statement: TextSchema, body: TextSchema, type: NoteTypeSchema, dontForget: Type.Boolean() },
+  { additionalProperties: false },
+)
+
+export const CaptureActionSchema = Type.Union([
+  ReadActionSchema,
+  Type.Object(
+    { action: Type.Literal("add"), vault: VaultSchema, note: CaptureDraftSchema },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Enum(["update", "succeed"]),
+      vault: VaultSchema,
+      path: PathSchema,
+      id: NoteIdSchema,
+      expectedHash: HashSchema,
+      note: CaptureDraftSchema,
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    {
+      action: Type.Literal("archive"),
+      vault: VaultSchema,
+      path: PathSchema,
+      id: NoteIdSchema,
+      expectedHash: HashSchema,
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object({ action: Type.Literal("finish") }, { additionalProperties: false }),
+])
+
+export const WriteObservationSchema = Type.Object(
+  {
+    kind: Type.Literal("write"),
+    operation: Type.Enum(["add", "update", "archive", "succeed"]),
+    status: Type.Enum(["applied", "conflict", "refused"]),
+    vault: VaultSchema,
+    path: PathSchema,
+    detail: TextSchema,
+  },
+  { additionalProperties: false },
+)
+
+export const RefusedObservationSchema = Type.Object(
+  {
+    kind: Type.Literal("refused"),
+    action: Type.Enum(["search", "get", "list", "add", "update", "archive", "succeed", "finish", "unparseable"]),
+    problems: Type.Array(TextSchema),
+  },
+  { additionalProperties: false },
+)
+
+export const CaptureObservationSchema = Type.Union([
+  ObservationSchema,
+  WriteObservationSchema,
+  RefusedObservationSchema,
+])
+
+export const CaptureInputSchema = Type.Object(
+  {
+    context: AgentContextSchema,
+    transcriptDelta: Type.Array(
+      Type.Object({ role: Type.Enum(["user", "assistant"]), text: TextSchema }, { additionalProperties: false }),
+      { minItems: 1 },
+    ),
+    observations: Type.Array(CaptureObservationSchema),
+    explicitSaves: Type.Array(ReadObservationSchema),
+    limits: Type.Object(
+      { maxBodyChars: Type.Integer({ minimum: 1 }), maxStatementChars: Type.Integer({ minimum: 1 }) },
+      { additionalProperties: false },
+    ),
+  },
+  { additionalProperties: false },
+)

package/src/domain/capture/tally.ts

@@ -0,0 +1,26 @@
+import { MIN_USER_MESSAGES_BEFORE_REVIEW } from "./constants.ts"
+import type { CaptureCadenceSettings, CaptureTally, FinishedTurn, FlushMoment, TurnOutcome } from "./types.ts"
+
+export function tallyUserMessage(tally: CaptureTally): CaptureTally {
+  return { ...tally, userMessages: tally.userMessages + 1 }
+}
+
+export function tallyTurn(
+  tally: CaptureTally,
+  turn: FinishedTurn,
+  settings: CaptureCadenceSettings | null,
+): TurnOutcome {
+  const counted = { ...tally, turnsSinceReview: tally.turnsSinceReview + 1 }
+  if (!settings?.reviewEnabled || turn.reviewActive) return { tally: counted, review: false }
+  counted.toolCallsSinceReview += turn.toolCalls
+  const reached =
+    counted.turnsSinceReview >= settings.nudgeInterval || counted.toolCallsSinceReview >= settings.nudgeToolCalls
+  if (!reached || counted.userMessages < MIN_USER_MESSAGES_BEFORE_REVIEW) return { tally: counted, review: false }
+  return { tally: { ...counted, turnsSinceReview: 0, toolCallsSinceReview: 0 }, review: true }
+}
+
+export function shouldFlush(tally: CaptureTally, settings: CaptureCadenceSettings, moment: FlushMoment): boolean {
+  if (tally.userMessages < settings.flushMinTurns) return false
+  if (moment === "compact") return settings.flushOnCompact
+  return settings.flushOnShutdown
+}

package/src/domain/capture/types.ts

@@ -0,0 +1,49 @@
+import type { Static } from "typebox"
+
+import type { Failed, Succeeded } from "#src/shared"
+import type {
+  CaptureActionSchema,
+  CaptureDraftSchema,
+  CaptureInputSchema,
+  CaptureObservationSchema,
+} from "./schemas.ts"
+
+export interface CaptureCadenceSettings {
+  nudgeInterval: number
+  nudgeToolCalls: number
+  flushMinTurns: number
+  reviewEnabled: boolean
+  flushOnCompact: boolean
+  flushOnShutdown: boolean
+}
+
+export interface CaptureTally {
+  userMessages: number
+  turnsSinceReview: number
+  toolCallsSinceReview: number
+}
+
+export interface FinishedTurn {
+  toolCalls: number
+  reviewActive: boolean
+}
+
+export interface TurnOutcome {
+  tally: CaptureTally
+  review: boolean
+}
+
+export type FlushMoment = "compact" | "shutdown"
+
+export type CaptureDraft = Static<typeof CaptureDraftSchema>
+export type CaptureAction = Static<typeof CaptureActionSchema>
+export type CaptureInput = Static<typeof CaptureInputSchema>
+export type CaptureObservation = Static<typeof CaptureObservationSchema>
+export type CaptureResult = Succeeded<CaptureAction> | Failed
+export type TranscriptMessage = CaptureInput["transcriptDelta"][number]
+
+export interface AddDiscriminant {
+  action: "add"
+}
+
+export type CaptureAdd = Extract<CaptureAction, AddDiscriminant>