@north-light/crouter 0.3.201 → 0.3.203

package/dist/commands/memory/write.js

@@ -1,44 +1,45 @@
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
-import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
-import { readText, writeText, pathExists } from '../../core/fs-utils.js';
-import { MEMORY_KINDS, MEMORY_SCOPES, VISIBILITY_RUNGS, resolveWriteTarget, memoryFilePath, buildOrigin, coerceGate, coerceAppliesTo, coerceReadWhen, serializeMemoryDoc, } from './shared.js';
+import { writeText, pathExists } from '../../core/fs-utils.js';
+import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, } from '../../core/memory/history.js';
+import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_VISIBILITY_RUNGS, MEMORY_SCOPES, resolveWriteTarget, memoryFilePath, buildOrigin, coerceGate, coerceAppliesTo, coerceReadWhen, overlayParam, serializeMemoryDoc, } from './shared.js';
 // A topic's memory set stays usable only when authors treat cohesion as a creation
 // gate; otherwise small corrections accumulate as overlapping leaves whose routing
 // lines cannot tell a future reader which one owns the topic.
 export const writeLeaf = defineLeaf({
     name: 'write',
-    description: 'create or update a memory document',
-    whenToUse: 'you are recording a new knowledge document or preference, or revising one that already exists — an existing <name> at the resolved scope is updated in place, so revision is also this leaf.',
+    description: 'create a memory document',
+    whenToUse: 'you are recording a new knowledge document or preference that does not exist yet. Creation only — a name already taken at the resolved scope is an error, because revising a stored document goes through `crtr memory edit`, which requires a rationale and records the revision.',
     help: {
         name: 'memory write',
-        summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
+        summary: 'create memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
         guide: 'Every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, so default each rung down.\n\n' +
             'Pick the kind. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.\n\n' +
             'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, and cross-repo conventions. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
-            'The visibility rungs `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc fits in a single sentence — a one-line preference or a one-sentence knowledge fact — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
+            GUIDE_VISIBILITY_RUNGS + '\n\n' +
             'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is scratch memory only this running node sees; it rides into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
             'A project root INDEX is the workspace front door. Name the physical doc INDEX, target the exact project with --dir, and use kind knowledge, system-prompt-visibility none, file-read-visibility content, and applies-to ".". Its envelope name comes from the owning project directory unless the document already carries an explicit name. Keep only the project constraints, key commands, architecture orientation, and conventions that differ from defaults. `crtr memory lint` validates this exact contract for every project managed by the selected profile.\n\n' +
             'Choose the hook — boot vs file context. System-prompt visibility is the boot catalog; file-read visibility fires on the applies-to routes. Put code-specific knowledge in the owning project store, give it the narrowest real file glob, and keep it out of boot when the file read is the useful trigger. Knowledge about a person or process usually has no file boundary, so set file-read-visibility none and route it through boot instead.\n\n' +
-            'Write the routing line (--when-and-why-to-read) first, before storing anything. The test for its because-clause: if it can be derived by paraphrasing the doc’s advice, it is a restatement, not a payoff — a real payoff names a consequence in the reader’s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" — the doc’s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising.\n\n' +
-            'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +
-            'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name — the same identifier `crtr memory read` takes (a directory INDEX is linked by its bare directory name). Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document, and `crtr memory read` lists a doc’s resolvable links alongside its body. There is no alias or label form.\n\n' +
+            'Write the routing line (--when-and-why-to-read) first, before storing anything. ' + GUIDE_ROUTING_LINE + '\n\n' +
+            GUIDE_PREDICATE_VOCABULARY + '\n\n' +
+            GUIDE_DOC_LINKS + '\n\n' +
             'When a doc grows long or information-rich, nest it into a graph instead of letting it become a scroll. The main doc at the topic’s path keeps the high-level, most load-bearing information, most important first; depth splits into reference docs under the topic’s directory (`area/topic/...`), each pointed at with a `[[link]]`. Split by subject: a leaf earns its link by covering a different subject a task might need on its own; a leaf of offloaded “further evidence”, examples, or references is never followed, so supporting material either sits in the main doc next to the point it supports or gets cut. The main doc is the entry point a reader can act from alone; a reference leaf is loaded only when the task needs that depth. Save reference leaves at `none` visibility on both axes — the link from the main doc is how they are found, so any higher rung just double-charges every boot or read for depth the graph already routes. Keep every doc as short as its job allows; `crtr memory lint` caps body length by rung and its findings carry the split guidance.\n\n' +
             'A directory INDEX earns existence only where the aggregate view beats the sum of per-file rungs. Aggregated child routing is automatic: `crtr memory read` of a directory INDEX appends every member’s routing line (`[[name]]: <when-and-why-to-read>`), so never author that list in the body. Two shapes pass: synthesis — an operating guide or the cluster’s mechanics, ordering, conditions, and relationships, content no single child can carry — and a pure gate — one preview line covering a cluster with one shared routing condition, the body adding nothing the automatic list does not. Otherwise skip the INDEX and let each doc’s own rung route it: frontmatter routing lines are self-maintaining, while an INDEX body describing its children is a hand-maintained copy that drifts. Never write an INDEX body that restates child names, paraphrases their routing lines, fronts a small directory of sharply named docs, or summarizes children a reader should open.\n\n' +
-            'Find before write. Prefer slightly expanding an existing document, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body whose merge into the existing document would make it harder to route or use. Group related docs with path names (area/topic). Provenance is automatic on create and preserved on update. Run `crtr memory lint` after authoring.\n\n' +
-            '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. If the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into. Omit the flag when you have no observed gap to record.',
+            'Find before write. Prefer slightly expanding an existing document with `crtr memory edit`, nesting genuinely separate depth under its topic, and updating the existing `when-and-why-to-read` (plus its INDEX router when present) over creating another similar memory. A new document earns its own identity only when it has a distinct read trigger and a coherent body whose merge into the existing document would make it harder to route or use. Group related docs with path names (area/topic). Provenance is stamped here and preserved by every later revision. Run `crtr memory lint` after authoring.\n\n' +
+            '--rationale is the gap this doc exists to close — the observed agent failure that prompted it, captured from user signal (a correction, a mistake you watched happen) rather than inferred from the doc’s own content. If the rationale is guessable from reading the doc, it is not the real one — a guessable gap is one agents do not actually fall into. Omit the flag when you have no observed gap to record.\n\n' +
+            'Revise an existing doc with `crtr memory edit`.',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity: one segment, or several joined with `/` to nest the document under a directory and group it with related docs → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
-            { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },
-            { kind: 'flag', name: 'when-and-why-to-read', type: 'string', required: false, constraint: 'ONE routing sentence: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the reader’s payoff — the consequence they secure for their task by reading — NEVER the doc summary, its rule, or that rule reworded as an outcome (a benefit-shaped restatement still fails). Rendered verbatim as the preview; required when creating.' },
-            { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form — a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
-            { kind: 'flag', name: 'system-prompt-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much of this document auto-loads into the system prompt / CLI help. Required when creating — there is no kind default; pick a rung explicitly.' },
-            { kind: 'flag', name: 'file-read-visibility', type: 'enum', choices: [...VISIBILITY_RUNGS], required: false, constraint: 'Rung controlling how much surfaces through file context. Required when creating — there is no kind default. Every value except none also requires at least one applies-to route in the resulting document.' },
-            { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
-            { kind: 'flag', name: 'applies-to', type: 'string', required: false, repeatable: true, constraint: 'One explicit file-context route per occurrence. In a project store, `.` fires when cwd/profile mounts that workspace during first-message assembly AND on any file read beneath the store\u2019s owning dir. Any other value is a glob matched after an actual file read against the absolute path, basename, and path relative to the owning project root. There is no positional fallback from where the memory file lives. Required whenever file-read-visibility is not none.' },
-            { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when — YAML/JSON object predicate over a read file’s own frontmatter using the same field/matcher vocabulary described in the guide.' },
-            { kind: 'flag', name: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) — the doc body becomes the command’s injected prompt. Default false: most docs are consulted, not invoked.' },
-            { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: 'Frontmatter rationale — the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting this flag on an update PRESERVES an existing rationale unchanged.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity: one segment, or several joined with `/` to nest the document under a directory and group it with related docs → memory/<name>.md at the resolved scope. The name must be free at that scope: an existing one is an error naming `crtr memory edit`.' },
+            overlayParam('kind', { required: true }),
+            overlayParam('when-and-why-to-read', { required: true }),
+            overlayParam('short-form'),
+            overlayParam('system-prompt-visibility', { required: true }, 'There is no kind default; pick a rung explicitly.'),
+            overlayParam('file-read-visibility', { required: true }, 'There is no kind default; pick a rung explicitly.'),
+            overlayParam('gate'),
+            overlayParam('applies-to'),
+            overlayParam('read-when'),
+            overlayParam('slash'),
+            { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: DOC_RATIONALE_CONSTRAINT },
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project directory. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile. `node` writes to the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) — the nearest scope, seen only by this running node, requires a node context.' },
             { kind: 'flag', name: 'dir', type: 'string', required: false, constraint: 'Exact project directory to write under — targets `<dir>/.crouter/memory/` regardless of cwd or ancestor stores, scaffolding `.crouter/` there if absent. THE way to place a doc in a specific project’s store (e.g. another project in your profile’s purview) without cd’ing there, and the only way to target a dir shadowed by an ancestor store. Implies --scope project; rejects --scope user/profile.' },
             { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or name to write under, for --scope profile. Default: the process CRTR_PROFILE_ID (the node\u2019s selected profile). Resolved through the same profile lookup as `crtr profile show`. Rejected (usage error) unless --scope profile is also selected \u2014 never silently ignored for another scope.' },
@@ -48,14 +49,15 @@ export const writeLeaf = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'The path-derived document name written.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user, project, profile, or node.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document — edit this file directly for later body tweaks instead of re-running write.' },
-            { name: 'created', type: 'boolean', required: true, constraint: 'true when a new document was created, false when an existing one was updated in place.' },
-            { name: 'frontmatter', type: 'object[]', required: true, constraint: 'The frontmatter options selected by this invocation, in document field order. Each: {key, value}. Preserved fields omitted from an update are not repeated.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back or list the inventory.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document.' },
+            { name: 'created', type: 'boolean', required: true, constraint: 'Always true on success — this leaf only creates. A name already taken at the resolved scope fails with a usage error naming `crtr memory edit`.' },
+            { name: 'frontmatter', type: 'object[]', required: true, constraint: 'The frontmatter options selected by this invocation, in document field order. Each: {key, value}.' },
+            { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the document’s append-only revision log, opened here with a `create` record.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back, revise it, or list the inventory.' },
         ],
         outputKind: 'object',
         effects: [
-            'Creates or overwrites memory/<name>.md at the resolved scope with the given frontmatter fields + stdin body.',
+            'Creates memory/<name>.md at the resolved scope with the given frontmatter fields + stdin body, and opens memory/.history/<name>.jsonl with a `create` record.',
         ],
     },
     run: async (input) => {
@@ -67,35 +69,20 @@ export const writeLeaf = defineLeaf({
         const dirArg = input['dir'];
         const { scope, memoryDir } = resolveWriteTarget(scopeArg, profileArg, dirArg);
         const path = memoryFilePath(memoryDir, name);
-        const created = !pathExists(path);
-        // CREATE requires the read-routing line that becomes the preview — without
-        // it every preview renders empty. UPDATE inherits it from the existing doc.
-        if (created && input['whenAndWhyToRead'] === undefined) {
-            throw usage(`creating ${name} requires --when-and-why-to-read: one read-routing sentence "When <circumstance>, this ${kind} should be read because <broader downstream payoff>." WHY is the reader’s payoff — what the read secures for their task — not the document summary, its rule, or that rule reworded as an outcome.`);
+        // Create-only. Revision goes through `edit`, which requires a rationale and
+        // records the change — a write that still overwrote would be a standing
+        // bypass of the audit trail. The error is the migration path.
+        if (pathExists(path)) {
+            throw usage(`${name} already exists at ${scope} scope — revise it with \`crtr memory edit ${name} --rationale "<why this revision>"\`, which records the change. \`write\` only creates.`, { memory: name, scope, path });
         }
-        // CREATE requires BOTH visibility rungs as an explicit, case-by-case call —
-        // there is no kind default to lean on. UPDATE inherits whatever the existing
-        // doc already carries.
-        if (created && input['systemPromptVisibility'] === undefined) {
-            throw usage(`creating ${name} requires --system-prompt-visibility: pick a rung explicitly (none|name|preview|content) — there is no kind default. See \`crtr memory write -h\` for what each rung means.`);
-        }
-        if (created && input['fileReadVisibility'] === undefined) {
-            throw usage(`creating ${name} requires --file-read-visibility: pick a rung explicitly (none|name|preview|content) — there is no kind default. See \`crtr memory write -h\` for what each rung means.`);
-        }
-        // In-place update: start from the existing frontmatter (preserving fields
-        // not passed this time), then overlay the provided ones. Create: start clean.
-        const frontmatter = created
-            ? {}
-            : { ...(parseFrontmatterGeneric(readText(path)).data ?? {}) };
-        // kind is required, always set. Optionals only overlay when provided so an
-        // update never erases a field the caller did not mention.
+        const frontmatter = {};
         frontmatter['kind'] = kind;
-        // Provenance is runtime-stamped ONCE, at creation — who/when/where authored
-        // this doc. An update inherits the existing `origin` via the spread above and
-        // never overwrites it, so it always points at the conversation that created
-        // the doc, not the last one to touch it. `crtr memory origin <name>` derefs it.
-        if (created)
-            frontmatter['origin'] = buildOrigin();
+        // Provenance is runtime-stamped ONCE, here — who/when/where authored this
+        // doc. Every later revision preserves it, so it always points at the
+        // conversation that created the doc, not the last one to touch it.
+        // `crtr memory origin <name>` derefs it.
+        const origin = buildOrigin();
+        frontmatter['origin'] = origin;
         const setIf = (key, value) => {
             if (value !== undefined)
                 frontmatter[key] = value;
@@ -115,6 +102,8 @@ export const writeLeaf = defineLeaf({
         if (input['slash'] === true)
             frontmatter['slash'] = true;
         setIf('rationale', input['rationale']);
+        // One field consumers read for recency, live from the first byte.
+        frontmatter['last-updated'] = origin['created'];
         const applies = frontmatter['applies-to'];
         const routes = typeof applies === 'string'
             ? [applies]
@@ -127,10 +116,13 @@ export const writeLeaf = defineLeaf({
         if (scope !== 'project' && routes.some((route) => route.trim() === '.')) {
             throw usage('applies-to "." is a project-store workspace mount route; use a real file glob or choose file-read-visibility none for user, profile, and node memory');
         }
-        writeText(path, serializeMemoryDoc(frontmatter, body));
-        // Confirm exactly the frontmatter choices made by this invocation. On an
-        // update, inherited fields stay in the file but do not masquerade as newly
-        // selected options in the result or its collapsed viewer preview.
+        const after = serializeMemoryDoc(frontmatter, body);
+        writeText(path, after);
+        const logPath = historyLogPathFor(memoryDir, path);
+        appendHistoryRecord(logPath, buildHistoryRecord({ op: 'create', before: '', after }));
+        // Confirm exactly the frontmatter choices made by this invocation — the
+        // runtime-stamped fields do not masquerade as selected options in the
+        // result or its collapsed viewer preview.
         const selectedKeys = [
             'kind',
             ...(input['whenAndWhyToRead'] !== undefined ? ['when-and-why-to-read'] : []),
@@ -149,9 +141,10 @@ export const writeLeaf = defineLeaf({
             kind,
             scope,
             path,
-            created,
+            created: true,
             frontmatter: selectedFrontmatter,
-            follow_up: `Read it back with \`crtr memory read ${name}\`, edit ${path} directly for a later body-only tweak, or browse the inventory with \`crtr memory list\`.`,
+            log_path: logPath,
+            follow_up: `Read it back with \`crtr memory read ${name}\`, revise it later with \`crtr memory edit ${name} --rationale "<why>"\`, or browse the inventory with \`crtr memory list\`.`,
         };
     },
 });

package/dist/commands/memory.js

@@ -1,10 +1,13 @@
 // `crtr memory` subtree — the document substrate (knowledge and preferences)
-// accessed via the CLI. Flat leaves: list, read, find, write, lint.
+// accessed via the CLI. Flat leaves: list, read, find, write, edit, history,
+// delete, origin, lint.
 import { defineBranch } from '../core/command.js';
 import { listLeaf } from './memory/list.js';
 import { readLeaf } from './memory/read.js';
 import { findLeaf } from './memory/find.js';
 import { writeLeaf } from './memory/write.js';
+import { editLeaf } from './memory/edit.js';
+import { historyLeaf } from './memory/history.js';
 import { deleteLeaf } from './memory/delete.js';
 import { originLeaf } from './memory/origin.js';
 import { lintLeaf } from './memory/lint.js';
@@ -19,8 +22,8 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read`/`write` once you know its name. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc — it renders as one boot-catalog entry whose system-prompt rung caps that subtree. File context is separate and explicit: `applies-to: "."` opens project context with the workspace; other globs fire after matching reads.',
+            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read` once you know its name. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `delete` removes, and `history` reads how a document reached its current state. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc — it renders as one boot-catalog entry whose system-prompt rung caps that subtree. File context is separate and explicit: `applies-to: "."` opens project context with the workspace; other globs fire after matching reads.',
         },
-        children: [listLeaf, readLeaf, findLeaf, writeLeaf, deleteLeaf, originLeaf, lintLeaf],
+        children: [listLeaf, readLeaf, findLeaf, writeLeaf, editLeaf, historyLeaf, deleteLeaf, originLeaf, lintLeaf],
     });
 }

package/dist/core/memory/history.d.ts

@@ -0,0 +1,54 @@
+/** Sidecar tree name under a store's `memory/` dir. Dot-prefixed and holding
+ *  only `.jsonl`, so every substrate scan (which filters to `*.md`, and in
+ *  `lint`'s case skips dot-dirs outright) passes it over without an exclusion
+ *  rule of its own. */
+export declare const HISTORY_DIR = ".history";
+/** File operations only — deliberately not a review lifecycle. */
+export type HistoryOp = 'create' | 'edit' | 'delete';
+export interface HistoryRecord {
+    op: HistoryOp;
+    at: string;
+    /** Authoring node id; absent for a human at a bare CLI. */
+    node?: string;
+    cwd: string;
+    /** Why this revision happened. Required on `edit`, absent otherwise. */
+    rationale?: string;
+    /** True when the body was declared a verbatim payload from the principal. */
+    verbatim?: boolean;
+    /** Complete document text before the mutation; empty for `create`. */
+    before: string;
+    /** Complete document text after the mutation; empty for `delete`. */
+    after: string;
+}
+/** The log path for a document, derived from its PHYSICAL path so the history
+ *  tree mirrors the doc tree exactly (`memory/area/topic.md` →
+ *  `memory/.history/area/topic.jsonl`). `memoryRoot` is the store's `memory/`
+ *  dir the doc lives under. */
+export declare function historyLogPathFor(memoryRoot: string, docPath: string): string;
+/** Stamp the runtime-owned fields of a record. Field insertion order IS the
+ *  serialized key order — the on-disk shape consumers read. */
+export declare function buildHistoryRecord(input: {
+    op: HistoryOp;
+    rationale?: string;
+    verbatim?: boolean;
+    before: string;
+    after: string;
+}): HistoryRecord;
+/** Append one record. Single write of one line — concurrent appends interleave
+ *  whole records, and every record stands alone, so no lock is needed. */
+export declare function appendHistoryRecord(logPath: string, record: HistoryRecord): void;
+/** Every record in a log, oldest first (append order). Revision numbers are
+ *  1-based positions in this array. */
+export declare function readHistoryRecords(logPath: string): HistoryRecord[];
+export interface ChangeSummary {
+    body_changed: boolean;
+    /** Frontmatter field names whose values differ between the two texts. */
+    frontmatter_changed: string[];
+}
+/** What one record changed, derived from its own two texts. `last-updated` is
+ *  excluded: the runtime stamps it on every edit, so listing it says nothing. */
+export declare function summarizeChange(before: string, after: string): ChangeSummary;
+/** Unified diff between two document texts, computed at read time. Dependency
+ *  free (an LCS over lines) — memory docs are lint-capped small, so the
+ *  quadratic table is never a cost. */
+export declare function unifiedDiff(before: string, after: string, context?: number): string;

package/dist/core/memory/history.js

@@ -0,0 +1,202 @@
+// Per-document revision history for the memory substrate: one append-only
+// JSONL sidecar per doc at `<store>/memory/.history/<name>.jsonl`, mirroring
+// the doc tree segment for segment. Every record carries the COMPLETE document
+// text before and after the mutation, so a reader never reconstructs a chain,
+// an interleaved concurrent append stays fully valid, and an out-of-band direct
+// file edit is visible as a record whose `before` differs from the prior
+// record's `after`. Diffs and revision numbers are derived at read time, never
+// stored.
+//
+// The raw file is the consumer contract: an external reader (a product surface
+// reading a store off disk) parses one JSON object per line and computes its
+// own diffs. Nothing here shells out to git.
+import { appendFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { ensureDir, pathExists, readText } from '../fs-utils.js';
+import { general } from '../errors.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+/** Sidecar tree name under a store's `memory/` dir. Dot-prefixed and holding
+ *  only `.jsonl`, so every substrate scan (which filters to `*.md`, and in
+ *  `lint`'s case skips dot-dirs outright) passes it over without an exclusion
+ *  rule of its own. */
+export const HISTORY_DIR = '.history';
+/** The log path for a document, derived from its PHYSICAL path so the history
+ *  tree mirrors the doc tree exactly (`memory/area/topic.md` →
+ *  `memory/.history/area/topic.jsonl`). `memoryRoot` is the store's `memory/`
+ *  dir the doc lives under. */
+export function historyLogPathFor(memoryRoot, docPath) {
+    const rel = relative(memoryRoot, docPath);
+    if (rel === '' || rel.startsWith('..')) {
+        throw general(`memory document ${docPath} is not inside its store root ${memoryRoot}`);
+    }
+    return join(memoryRoot, HISTORY_DIR, rel.replace(/\.md$/i, '') + '.jsonl');
+}
+/** Stamp the runtime-owned fields of a record. Field insertion order IS the
+ *  serialized key order — the on-disk shape consumers read. */
+export function buildHistoryRecord(input) {
+    const env = process.env;
+    const record = {
+        op: input.op,
+        at: new Date().toISOString(),
+        ...(env['CRTR_NODE_ID'] ? { node: env['CRTR_NODE_ID'] } : {}),
+        cwd: env['CRTR_NODE_CWD'] ?? process.cwd(),
+        ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
+        ...(input.verbatim === true ? { verbatim: true } : {}),
+        before: input.before,
+        after: input.after,
+    };
+    return record;
+}
+/** Append one record. Single write of one line — concurrent appends interleave
+ *  whole records, and every record stands alone, so no lock is needed. */
+export function appendHistoryRecord(logPath, record) {
+    ensureDir(dirname(logPath));
+    appendFileSync(logPath, JSON.stringify(record) + '\n', 'utf8');
+}
+/** Every record in a log, oldest first (append order). Revision numbers are
+ *  1-based positions in this array. */
+export function readHistoryRecords(logPath) {
+    if (!pathExists(logPath))
+        return [];
+    const lines = readText(logPath).split('\n');
+    const records = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.trim() === '')
+            continue;
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch {
+            throw general(`corrupt history record at ${logPath}:${i + 1} — the line is not valid JSON`, {
+                next: 'Inspect that line directly; the surrounding records are self-contained and still readable.',
+            });
+        }
+    }
+    return records;
+}
+/** What one record changed, derived from its own two texts. `last-updated` is
+ *  excluded: the runtime stamps it on every edit, so listing it says nothing. */
+export function summarizeChange(before, after) {
+    const b = parseFrontmatterGeneric(before);
+    const a = parseFrontmatterGeneric(after);
+    const bData = b.data ?? {};
+    const aData = a.data ?? {};
+    const keys = new Set([...Object.keys(bData), ...Object.keys(aData)]);
+    keys.delete('last-updated');
+    const changed = [...keys]
+        .filter((k) => JSON.stringify(bData[k]) !== JSON.stringify(aData[k]))
+        .sort((x, y) => x.localeCompare(y));
+    return { body_changed: b.body !== a.body, frontmatter_changed: changed };
+}
+/** Unified diff between two document texts, computed at read time. Dependency
+ *  free (an LCS over lines) — memory docs are lint-capped small, so the
+ *  quadratic table is never a cost. */
+export function unifiedDiff(before, after, context = 3) {
+    const { lines: a, terminated: aTerm } = toLines(before);
+    const { lines: b, terminated: bTerm } = toLines(after);
+    // Diff on keys, not raw text: an unterminated final line is a DIFFERENT line
+    // from the same text terminated, so dropping a trailing newline is a real
+    // change rather than an empty diff.
+    const ops = diffOps(diffKeys(a, aTerm), diffKeys(b, bTerm));
+    // Each changed op claims `context` ops on either side; overlapping claims
+    // merge into one hunk.
+    const ranges = [];
+    for (let i = 0; i < ops.length; i += 1) {
+        if (ops[i].tag === ' ')
+            continue;
+        const from = Math.max(0, i - context);
+        const to = Math.min(ops.length, i + context + 1);
+        const last = ranges[ranges.length - 1];
+        if (last !== undefined && from <= last.to)
+            last.to = Math.max(last.to, to);
+        else
+            ranges.push({ from, to });
+    }
+    if (ranges.length === 0)
+        return '';
+    // Line numbers each op sits at, in the before and after texts.
+    const aAt = [];
+    const bAt = [];
+    let aLine = 0;
+    let bLine = 0;
+    for (const op of ops) {
+        aAt.push(aLine);
+        bAt.push(bLine);
+        if (op.tag !== '+')
+            aLine += 1;
+        if (op.tag !== '-')
+            bLine += 1;
+    }
+    const out = [];
+    for (const { from, to } of ranges) {
+        const slice = ops.slice(from, to);
+        const aCount = slice.filter((op) => op.tag !== '+').length;
+        const bCount = slice.filter((op) => op.tag !== '-').length;
+        // A side contributing no lines is `0,0` — an empty file has no line 1.
+        out.push(`@@ -${aCount === 0 ? 0 : aAt[from] + 1},${aCount} +${bCount === 0 ? 0 : bAt[from] + 1},${bCount} @@`);
+        for (let i = from; i < to; i += 1) {
+            const op = ops[i];
+            out.push(op.tag + (op.tag === '+' ? b[op.index] : a[op.index]));
+            const endsA = op.tag !== '+' && !aTerm && aAt[i] === a.length - 1;
+            const endsB = op.tag !== '-' && !bTerm && bAt[i] === b.length - 1;
+            if (endsA || endsB)
+                out.push(NO_NEWLINE_MARKER);
+        }
+    }
+    return out.join('\n');
+}
+const NO_NEWLINE_MARKER = '\';
+// U+0000 cannot occur in a memory document, so it can never collide with text.
+const NO_NEWLINE_KEY = '\u0000no-newline-at-eof';
+function diffKeys(lines, terminated) {
+    if (terminated || lines.length === 0)
+        return lines;
+    return lines.map((line, i) => (i === lines.length - 1 ? line + NO_NEWLINE_KEY : line));
+}
+/** Split into diffable lines. A final `\n` TERMINATES the last line rather than
+ *  opening an empty one, so `foo\n` is one line; a text without it is flagged so
+ *  the diff can mark it, the way a unified patch must. */
+function toLines(text) {
+    if (text === '')
+        return { lines: [], terminated: true };
+    const terminated = text.endsWith('\n');
+    const lines = text.split('\n');
+    if (terminated)
+        lines.pop();
+    return { lines, terminated };
+}
+function diffOps(a, b) {
+    const n = a.length;
+    const m = b.length;
+    // lcs[i][j] = length of the longest common subsequence of a[i..] and b[j..].
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ tag: ' ', index: i });
+            i += 1;
+            j += 1;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            ops.push({ tag: '-', index: i });
+            i += 1;
+        }
+        else {
+            ops.push({ tag: '+', index: j });
+            j += 1;
+        }
+    }
+    for (; i < n; i += 1)
+        ops.push({ tag: '-', index: i });
+    for (; j < m; j += 1)
+        ops.push({ tag: '+', index: j });
+    return ops;
+}

package/dist/core/memory-resolver.d.ts

@@ -26,6 +26,11 @@ export interface MemoryDoc {
     scope: MemoryScope;
     /** Absolute path to the resolved .md file. */
     path: string;
+    /** Absolute path of the `memory/` dir this doc loaded from — the store root
+     *  its identity is relative to. Sidecar trees that mirror the doc tree (the
+     *  revision-history log) are derived from `path` relative to this. For a
+     *  plugin doc it is that plugin's own memory dir. */
+    root: string;
     /** Raw, uncoerced frontmatter record (null when the doc has no frontmatter). */
     frontmatter: Record<string, unknown> | null;
     /** Document body, with the frontmatter block stripped. */
@@ -64,6 +69,15 @@ export interface MemoryResolutionOpts {
      *  persona resolution, which stay on the flat ancestor+profile stack. */
     includeDescendants?: boolean;
 }
+/** The native (non-plugin) store dirs in resolution precedence — node >
+ *  project stack > profile > user, builtin excluded as a read-only corpus.
+ *  Addresses a store directly when the document itself may be absent, which is
+ *  how a DELETED doc's revision log is still found: history outlives the doc,
+ *  so its lookup cannot go through document resolution. */
+export declare function nativeMemoryStoresInPrecedence(scope?: MemoryScope, includeDescendants?: boolean): {
+    scope: MemoryScope;
+    memoryDir: string;
+}[];
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export declare function memoryDocId(doc: MemoryDoc): string;
 /** Whose memory view is being resolved: the workspace dir, profile, and node
@@ -105,6 +119,13 @@ export declare function listProjectMemoryDocs(startDir?: string, profileId?: str
  *  native docs are emitted before enabled-plugin docs, so native wins on the
  *  caller's first-wins dedup. */
 export declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean, includeDescendants?: boolean): MemoryDoc[];
+/** Resolve a document NAME against a `.history` tree, which mirrors the doc
+ *  tree segment for segment with `.jsonl` in place of `.md`. Reuses the doc
+ *  resolution rules so a log outlives its doc under the same name the doc had:
+ *  numeric prefixes stay prefix-blind (`00-topic.md` logged at
+ *  `.history/00-topic.jsonl` still answers to `topic`) and a bare directory
+ *  name falls back to its INDEX log. Returns null when nothing resolves. */
+export declare function resolveHistoryLogPath(historyDir: string, segments: string[]): string | null;
 export interface MemoryDocSnapshot {
     /** Every document in default scope precedence order, loaded once. */
     docs: readonly MemoryDoc[];