pi-obsidian-memory 0.0.0 → 0.1.0

package/README.md

@@ -1,15 +1,181 @@
 # 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 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.
+Coding agents forget everything between sessions. This extension gives pi durable memory that changes its future
+behavior, that you can read and edit in Obsidian, and that lives in any folder you choose. Memory is two layers of
+dedicated vaults: one global vault about you (how to address you, preferences, patterns, lessons) and one vault per
+project. Notes are plain Markdown, written in English whatever language you speak, and never deleted: retired notes
+move to `archive/`. See [docs/VISION.md](docs/VISION.md) for the decisions behind it.
 
-- 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`).
+> **Status:** runs on Windows, macOS and Linux; CI runs the unit tests on all three and the end-to-end suite runs on
+> Windows. Requires Node 22.19 or later.
 
-Documentação do projeto em [`docs/`](docs/). Decisões em [`docs/OPEN-QUESTIONS.md`](docs/OPEN-QUESTIONS.md).
+## Install
 
-## Licença
+From git:
+
+```bash
+pi install git:github.com/DavyMassoneto/pi-obsidian-memory
+```
+
+From a local clone (loaded from that path, not copied; pi does not install its dependencies, so do it first):
+
+```bash
+npm install --omit=dev --prefix ./pi-obsidian-memory
+pi install ./pi-obsidian-memory
+```
+
+Both write the package to `~/.pi/agent/settings.json`; add `--local` to write `.pi/settings.json` instead (pi reads it
+only after project trust is granted). You can also add the source yourself:
+
+```json
+{
+  "packages": ["git:github.com/DavyMassoneto/pi-obsidian-memory"]
+}
+```
+
+`pi list` shows installed packages. To try it for one run without installing:
+`pi -e git:github.com/DavyMassoneto/pi-obsidian-memory`. Pi's own docs cover every option (`docs/packages.md`).
+
+## Quick start
+
+1. `/memory-setup` chooses where the global vault lives (create a new one or attach an existing folder), asks which
+   chat model to use for capture (the model in use is the default) and for the memory agent (a small, cheap one is
+   enough; the list is sorted by price, cheapest first), shows the
+   warnings that apply and writes the config. Run again, it is the settings screen: every setting, and the projects,
+   one select at a time.
+2. In a project folder, `/memory-init` registers it with its own vault (created when missing). An unregistered folder
+   gets the global vault only.
+
+Both commands need pi's UI. Until `/memory-setup` is done there is no memory, and session start says so. The config is
+`pi-obsidian-memory/config.json` in the pi agent directory, outside the vaults; every key is described in
+[docs/config.md](docs/config.md). Nothing needs editing by hand. Changing a vault leaves the old one as it was.
+
+## What works
+
+### Tools
+
+The LLM uses these; the ones that write act only on your explicit request ("remember this"), and nothing in the prompt
+nudges it to save on its own.
+
+| Tool | Does |
+|---|---|
+| `memory_search` | Finds notes in the global vault, the project vault or both (words and meaning together) |
+| `memory_get` | Reads a note in full with its problems, a folder's index, or anything under `archive/` |
+| `memory_add` | Saves a new note when you ask to remember something |
+| `memory_update` | Changes a note you asked to change; keeps its identity |
+| `memory_archive` | Moves a note to `archive/` |
+| `memory_succeed` | Replaces a note with a successor; the two link to each other |
+
+`memory_update`, `memory_archive` and `memory_succeed` first need a `memory_get` of the same note in the session, and
+refuse a note that changed on disk since (an edit you made in Obsidian is never overwritten). A shipped skill,
+`obsidian-memory`, teaches the agent the layout, note types and these rules; it is never written to a vault.
+
+### Commands
+
+| Command | Does |
+|---|---|
+| `/memory-setup` | First setup (vault and models); afterwards the settings screen for every setting and the projects |
+| `/memory-init` | Registers the working folder as a project with its own vault |
+| `/memory-doctor` | Reports problems in the vaults and the config; offers to complete blank notes after you confirm |
+| `/memory-export` | Writes both vaults to a new `.zip` (never overwrites; refuses a folder inside a vault) |
+
+`/memory-doctor` lists invalid notes, blank notes, duplicate ids, leftover temporary files and folders over the
+notes-per-folder limit, then checks the chat model, the embeddings and the decision model. Every other problem is left
+as it is on disk.
+
+### Memory in the conversation
+
+- **Don't forget.** Mark a note with `dontForget: true` in its frontmatter. Every such note, in both vaults, is loaded
+  in full at session start, with no limit.
+- **Relevant memory per message.** On each message, a fast decision model (a classifier that answers yes/no
+  probabilities; it never searches or generates) decides whether memory is needed. If so, the memory agent (a chat model)
+  searches and reads, the decision model scores each candidate note, and the relevant ones are added after your message. Earlier
+  messages are never rewritten, so the prompt cache holds; a loaded note that changed is added again, marked as
+  replacing the earlier copy. A loaded note that is gone is reported as "the note was archived or deleted"; one still
+  there but unusable, as "the note is still there but cannot be used (<problem>)"; one whose state is unknown, an
+  invalid config included, as "the note cannot be read (<problem>)". Session start also loads relevant notes within
+  `context.budgetChars` (12,000 by default). The decision model is Jev by default (by API; it needs `TYPESAFE_API_KEY`;
+  $0.042 per million input tokens, per docs.typesafe.ai), working from TypeSafe's starting cutoffs (0.5/0.5). Laya,
+  run locally, is an optional choice that needs explicit `gateThreshold` and `relevanceThreshold`: it ships none
+  because its gate measured at chance (see [decision-thresholds](docs/decision-thresholds.md)), so with Laya and no
+  cutoffs per-message memory is off and each session tells you. Setup steps are in
+  [Running the decision model](docs/config.md#running-the-decision-model). If the decision model is unavailable
+  nothing is added and you are told once per session; no other model takes over.
+- **Automatic capture.** As in pi-hermes-memory, a background review of the conversation saves, updates, archives and
+  succeeds notes every `capture.nudgeInterval` assistant turns (10) or `capture.nudgeToolCalls` tool calls (15), once
+  the session has three user messages. What was not yet reviewed is also reviewed before compaction and when the
+  session ends, once it has `capture.flushMinTurns` user messages (6). It never asks you anything: what it is unsure
+  of is not saved. Its judgement quality is not yet proven against a real model.
+- **Semantic search.** `memory_search` fuses words and meaning. The default is a local multilingual model (about
+  135 MB), downloaded when needed, without asking; OpenAI and Google are the alternatives. The index lives outside the
+  vaults and is rebuilt from the notes whenever needed.
+
+### Vault guard
+
+The LLM reaches vault files only through the memory tools. The extension refuses `read`, `write`, `edit`, `grep`, `find`
+and `ls` on a vault, `bash`/`powershell` commands that write a vault path out, and junctions and symlinks into a vault.
+You, and Obsidian, are not the LLM and stay free.
+
+Accepted as they are (your decision, 2026-10-17): reading a vault through a path the shell builds indirectly
+(variables, globs, scripts), tools of other extensions, and foreground subagents, which load no extensions. Creating
+hardlinks through the shell is refused by the shell-edit guard. Details in
+[docs/ROADMAP.md](docs/ROADMAP.md#2-memory-the-agent-can-read-vault-access-only).
+
+Paths are compared ignoring case on Windows and macOS and with case on Linux, whatever the volume: a case-sensitive
+macOS volume is still compared ignoring case, and a case-insensitive mount on Linux is still compared with case.
+
+### Shell-edit guard
+
+Before every `bash`/`powershell` call, Jev (`jev-latest`, which needs `TYPESAFE_API_KEY`) scores whether the command
+edits a file through a redirection, an in-place edit, inline code, a script that writes, a copy or download that
+creates a file, or a hardlink. A score at or above its cutoff refuses the call and points to `edit` and `write`;
+when Jev cannot answer, the call is refused. The cutoffs and how they were measured are in
+[docs/shell-edit-cutoffs.md](docs/shell-edit-cutoffs.md).
+
+### Dashboard
+
+Setup and init write `Memory.base` at each vault root when it is missing, with views for all notes, Don't forget and
+Archive (file name, folder, type, Don't forget, updated). Your edits to it are kept. It only displays.
+
+## Privacy
+
+- Capture and the memory agent send conversation and note content to the chat model you choose.
+- Jev, the default decision model, sends your messages and candidate notes to TypeSafe; Laya, the optional local choice, runs on your machine.
+- Choosing a remote embeddings provider (OpenAI, Google) sends note content and queries to it.
+- `/memory-setup` warns about each of these before writing, as a plain warning with no question; nothing is asked at
+  runtime, and no other provider ever takes the place of the one you chose.
+- Secrets are saved as written: the vault is yours, with no masking or blocking.
+- Credentials come from pi or the environment; `config.json` never holds a key.
+
+## Development
+
+Tested with pi `1.3.0` and TypeBox `1.3.27`, pinned as development dependencies. Pi provides both at runtime;
+following its package contract, they are wildcard peers, not bundled runtime dependencies.
+
+```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, with a temporary agent folder and vaults
+npm run test:model    # live tests: real models and network
+pi -e ./src/pi/extension.ts
+```
+
+`npm test` needs no model and no network. `npm run test:e2e` uses the real Haiku (`cc/claude-haiku-5-5`) through
+OmniRoute, loaded in pi by `pi-omniroute-sync`, and the real Jev. It reads `OMNIROUTE_URL`, `OMNIROUTE_API_KEY` and
+`TYPESAFE_API_KEY` from the environment and runs one test file at a time. CI runs it on windows-latest (the secrets
+have the same names). The Laya tests use a real `laya-serve` from `tmp/laya-venv` and run only on request:
+`npx vitest run --project e2e-laya`.
+
+`npm run test:model` downloads the local embedding model (about 135 MB) to a cache folder outside the repository
+(`%LOCALAPPDATA%\pi-obsidian-memory-bench\models`) and is not part of `npm test`.
+
+The roadmap is in [docs/ROADMAP.md](docs/ROADMAP.md); the note format is in
+[docs/vault-format.md](docs/vault-format.md).
+
+## License
 
 [MIT](LICENSE)

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "pi-obsidian-memory",
-  "version": "0.0.0",
-  "description": "Memória de longo prazo para o pi coding agent em vaults do Obsidian (OneDrive opcional)",
+  "version": "0.1.0",
+  "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,16 +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.mjs"
+    "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"
+  },
+  "pi": {
+    "extensions": [
+      "./src/pi/extension.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@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"
   },
-  "publishConfig": {
-    "access": "public"
+  "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>

package/src/domain/capture/validate.ts

@@ -0,0 +1,75 @@
+import { Value } from "typebox/value"
+
+import { checkAgentVault, checkReadAction, hasReadIdentity, type MemoryIdentity } from "#src/domain/memory-agent"
+import { checkNoteText } from "#src/domain/note"
+import { checkMemoryFolder, checkVaultPath, joinVaultPath } from "#src/domain/vault-path"
+import { CaptureActionSchema } from "./schemas.ts"
+import type { CaptureAction, CaptureAdd, CaptureDraft, CaptureInput, CaptureResult } from "./types.ts"
+
+export function parseCaptureAction(text: string, input: CaptureInput): CaptureResult {
+  try {
+    const action = JSON.parse(text)
+    if (!Value.Check(CaptureActionSchema, action)) {
+      return { succeeded: false, problems: ["Invalid capture action"] }
+    }
+    const problems = checkCaptureAction(action, input)
+    if (problems.length > 0) return { succeeded: false, problems }
+    return { succeeded: true, output: action }
+  } catch {
+    return { succeeded: false, problems: ["Invalid capture JSON"] }
+  }
+}
+
+function checkCaptureAction(action: CaptureAction, input: CaptureInput): string[] {
+  if (action.action === "finish") return []
+  if (action.action === "search" || action.action === "get" || action.action === "list") {
+    return checkReadAction(action, input.context)
+  }
+  const problems = checkAgentVault(action.vault, input.context)
+  if (action.action !== "add") {
+    const identity = { vault: action.vault, path: action.path, id: action.id, hash: action.expectedHash }
+    problems.push(...checkMutation(identity, input))
+  }
+  if (action.action !== "archive") problems.push(...checkDraft(action.note, input))
+  if (action.action === "add") problems.push(...checkDuplicate(action, input))
+  if ((action.action === "add" || action.action === "succeed") && action.note.folder.length === 0) {
+    problems.push("New capture notes require a subject folder")
+  }
+  if (
+    action.action === "update" &&
+    (action.path.slice(-3).toLowerCase() !== ".md" ||
+      action.path.slice(0, -3) !== joinVaultPath(action.note.folder, action.note.statement))
+  ) {
+    problems.push("Update must keep the read note's folder and statement")
+  }
+  return problems
+}
+
+function checkMutation(identity: MemoryIdentity, input: CaptureInput): string[] {
+  const latest = input.observations.findLast(
+    (item) =>
+      (item.kind === "read" || item.kind === "write") && item.vault === identity.vault && item.path === identity.path,
+  )
+  const reads = input.observations.filter((item) => item.kind !== "write" && item.kind !== "refused")
+  if (latest?.kind !== "read" || !hasReadIdentity(identity, reads)) {
+    return ["Mutation requires a fresh matching read identity and hash"]
+  }
+  return checkVaultPath(identity.path)
+}
+
+function checkDraft(note: CaptureDraft, input: CaptureInput): string[] {
+  return [...checkNoteText(note.statement, note.body, input.limits), ...checkMemoryFolder(note.folder)]
+}
+
+function checkDuplicate(action: CaptureAdd, input: CaptureInput): string[] {
+  const existing = [...input.explicitSaves, ...input.observations.filter((item) => item.kind === "read")]
+  const path = joinVaultPath(action.note.folder, `${action.note.statement}.md`).toLowerCase()
+  const duplicate = existing.some(
+    (read) =>
+      read.vault === action.vault &&
+      (read.path.toLowerCase() === path ||
+        (read.statement === action.note.statement && read.body === action.note.body)),
+  )
+  if (duplicate) return ["Existing point requires an update or finish, not a duplicate add"]
+  return []
+}