agent-working-memory 0.9.1 → 0.11.0

package/src/engine/staging.ts

@@ -1,74 +1,74 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Staging Buffer — weak signal handler.
- *
- * Observations that don't meet the salience threshold for active memory
- * go to staging. The staging buffer periodically:
- *   1. Checks staged engrams against active memory for resonance
- *   2. Promotes resonant engrams to active
- *   3. Discards expired engrams that never resonated
- *
- * Modeled on hippocampal consolidation — provisional encoding
- * that only persists if reactivated.
- */
-
-import type { IEngramStore as EngramStore } from '../storage/store.js';
-import type { ActivationEngine } from './activation.js';
-
-export class StagingBuffer {
-  private store: EngramStore;
-  private engine: ActivationEngine;
-  private checkInterval: ReturnType<typeof setInterval> | null = null;
-
-  constructor(store: EngramStore, engine: ActivationEngine) {
-    this.store = store;
-    this.engine = engine;
-  }
-
-  /**
-   * Start the periodic staging check.
-   */
-  start(intervalMs: number = 60_000): void {
-    this.checkInterval = setInterval(() => this.sweep(), intervalMs);
-  }
-
-  stop(): void {
-    if (this.checkInterval) {
-      clearInterval(this.checkInterval);
-      this.checkInterval = null;
-    }
-  }
-
-  /**
-   * Sweep staged engrams: promote or discard.
-   */
-  async sweep(): Promise<{ promoted: string[]; discarded: string[] }> {
-    const promoted: string[] = [];
-    const discarded: string[] = [];
-
-    const expired = await this.store.getExpiredStaging();
-    for (const engram of expired) {
-      // Check if this engram resonates with active memory
-      const results = await this.engine.activate({
-        agentId: engram.agentId,
-        context: `${engram.concept} ${engram.content}`,
-        limit: 3,
-        minScore: 0.3,
-        internal: true,
-      });
-
-      if (results.length > 0) {
-        // Resonance found — promote to active
-        await this.store.updateStage(engram.id, 'active');
-        promoted.push(engram.id);
-      } else {
-        // No resonance — discard
-        await this.store.deleteEngram(engram.id);
-        discarded.push(engram.id);
-      }
-    }
-
-    return { promoted, discarded };
-  }
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Staging Buffer — weak signal handler.
+ *
+ * Observations that don't meet the salience threshold for active memory
+ * go to staging. The staging buffer periodically:
+ *   1. Checks staged engrams against active memory for resonance
+ *   2. Promotes resonant engrams to active
+ *   3. Discards expired engrams that never resonated
+ *
+ * Modeled on hippocampal consolidation — provisional encoding
+ * that only persists if reactivated.
+ */
+
+import type { IEngramStore as EngramStore } from '../storage/store.js';
+import type { ActivationEngine } from './activation.js';
+
+export class StagingBuffer {
+  private store: EngramStore;
+  private engine: ActivationEngine;
+  private checkInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(store: EngramStore, engine: ActivationEngine) {
+    this.store = store;
+    this.engine = engine;
+  }
+
+  /**
+   * Start the periodic staging check.
+   */
+  start(intervalMs: number = 60_000): void {
+    this.checkInterval = setInterval(() => this.sweep(), intervalMs);
+  }
+
+  stop(): void {
+    if (this.checkInterval) {
+      clearInterval(this.checkInterval);
+      this.checkInterval = null;
+    }
+  }
+
+  /**
+   * Sweep staged engrams: promote or discard.
+   */
+  async sweep(): Promise<{ promoted: string[]; discarded: string[] }> {
+    const promoted: string[] = [];
+    const discarded: string[] = [];
+
+    const expired = await this.store.getExpiredStaging();
+    for (const engram of expired) {
+      // Check if this engram resonates with active memory
+      const results = await this.engine.activate({
+        agentId: engram.agentId,
+        context: `${engram.concept} ${engram.content}`,
+        limit: 3,
+        minScore: 0.3,
+        internal: true,
+      });
+
+      if (results.length > 0) {
+        // Resonance found — promote to active
+        await this.store.updateStage(engram.id, 'active');
+        promoted.push(engram.id);
+      } else {
+        // No resonance — discard
+        await this.store.deleteEngram(engram.id);
+        discarded.push(engram.id);
+      }
+    }
+
+    return { promoted, discarded };
+  }
+}

package/src/index.ts

@@ -3,6 +3,7 @@
 import { readFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
 import { resolve, dirname, basename } from 'node:path';
 import Fastify from 'fastify';
+import { VERSION } from './version.js';
 
 // Load .env file if present (no external dependency)
 try {
@@ -202,7 +203,7 @@ async function main() {
 
   // Start server
   await app.listen({ port: PORT, host: '0.0.0.0' });
-  console.log(`AgentWorkingMemory v0.8.5 listening on port ${PORT}`);
+  console.log(`AgentWorkingMemory v${VERSION} listening on port ${PORT}`);
 
   // Graceful shutdown
   const shutdown = async () => {

package/src/mcp.ts

@@ -29,7 +29,7 @@
  */
 
 import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { resolve, basename } from 'node:path';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 // Load .env file if present (no external dependency)
@@ -75,6 +75,8 @@ import { DEFAULT_AGENT_CONFIG } from './types/agent.js';
 import { embed } from './core/embeddings.js';
 import { startSidecar } from './hooks/sidecar.js';
 import { initLogger, log, getLogPath } from './core/logger.js';
+import { VERSION } from './version.js';
+import { buildPack, INTERVIEW_QUESTIONS } from './onboard/index.js';
 import { liteCompress, retrieveOriginal } from './core/lite-compress.js';
 import { queryPeerDecisions, formatPeerDecisions } from './coordination/peer-decisions.js';
 
@@ -86,7 +88,7 @@ const INCOGNITO = process.env.AWM_INCOGNITO === '1' || process.env.AWM_INCOGNITO
 
 if (INCOGNITO) {
   console.error('AWM: incognito mode — all memory tools disabled, nothing will be recorded');
-  const server = new McpServer({ name: 'agent-working-memory', version: '0.8.8' });
+  const server = new McpServer({ name: 'agent-working-memory', version: VERSION });
   const transport = new StdioServerTransport();
   server.connect(transport).catch(err => {
     console.error('MCP server failed:', err);
@@ -141,7 +143,7 @@ let coordDb: import('better-sqlite3').Database | null = null;
 
 const server = new McpServer({
   name: 'agent-working-memory',
-  version: '0.8.8',
+  version: VERSION,
 });
 
 server.registerResource(
@@ -639,6 +641,15 @@ Use this at the start of every session or after compaction to pick up where you
   async () => {
     const checkpoint = await store.getCheckpoint(AGENT_ID);
 
+    // Cold-store nudge: an empty store means the agent has nothing to recall — offer to warm-start.
+    let coldStoreNudge = '';
+    try {
+      const activeCount = (await store.getEngramsByAgent(AGENT_ID)).length;
+      if (activeCount < 3) {
+        coldStoreNudge = `🌱 **This memory store is nearly empty (${activeCount} ${activeCount === 1 ? 'memory' : 'memories'}).** Warm-start it before other work: recall the "onboard a new project" skill and follow it — or call \`onboard_scan\` on this project's docs/repo, refine the results, and save them with \`memory_write\` (canonical). Recall becomes useful immediately.`;
+      }
+    } catch { /* count is best-effort */ }
+
     const now = Date.now();
     const idleMs = checkpoint
       ? now - checkpoint.auto.lastActivityAt.getTime()
@@ -717,6 +728,7 @@ Use this at the start of every session or after compaction to pick up where you
         : '';
     log(AGENT_ID, 'restore', `idle=${idleMin}min checkpoint=${!!checkpoint?.executionState} recalled=${recalledMemories.length} lastWrite=${lastWrite?.concept ?? 'none'}${fullConsolidationTriggered ? ' FULL_CONSOLIDATION' : ''}`);
     parts.push(`Idle: ${idleMin}min${consolidationNote}`);
+    if (coldStoreNudge) parts.push(`\n${coldStoreNudge}`);
 
     if (checkpoint?.executionState) {
       const s = checkpoint.executionState;
@@ -774,6 +786,53 @@ Use this at the start of every session or after compaction to pick up where you
   }
 );
 
+// --- Onboarding Tools (warm-start a cold store) ---
+
+server.tool(
+  'onboard_scan',
+  `Scan a project's documentation + repository and return CANDIDATE memories to seed a cold store.
+
+Use this when the store is empty / you're new to a project. The scan is deterministic
+(real file contents, not guesses) — YOUR job is to refine the candidates into atomic,
+recall-shaped memories, run the interview (onboard_questions), confirm with the user, then
+save the good ones with memory_write (memory_class="canonical"). Nothing is saved by this tool.`,
+  {
+    docs: z.array(z.string()).optional()
+      .describe('Doc files/dirs to scan (Markdown/text). Defaults to the repo (or cwd).'),
+    repo: z.string().optional()
+      .describe('Repo root — also derives stack (package.json) + layout memories.'),
+    project: z.string().optional()
+      .describe('Project name (becomes a tag). Defaults to the repo/dir name.'),
+    purpose: z.string().optional()
+      .describe('The goal of this memory system, if known — becomes the anchor memory.'),
+  },
+  async (params) => {
+    const repo = params.repo;
+    const docs = params.docs && params.docs.length ? params.docs : [repo ?? process.cwd()];
+    const project = params.project ?? basename(resolve(repo ?? docs[0] ?? process.cwd()));
+    const pack = buildPack({ docs, repo, project, agentId: AGENT_ID, purpose: params.purpose });
+    log(AGENT_ID, 'onboard', `scan ${docs.join(',')}${repo ? ' +repo' : ''} → ${pack.memories.length} candidates`);
+    const text = [
+      `Scanned ${docs.join(', ')}${repo ? ` (+repo ${repo})` : ''} → ${pack.memories.length} CANDIDATE memories (NOT saved).`,
+      `Next: refine each into an atomic memory (lead with the fact + identifiers), run onboard_questions,`,
+      `confirm with the user, then save the good ones with memory_write (memory_class="canonical").`,
+      ``,
+      JSON.stringify({ project, candidates: pack.memories, questions: pack.questions }, null, 2),
+    ].join('\n');
+    return { content: [{ type: 'text' as const, text }] };
+  }
+);
+
+server.tool(
+  'onboard_questions',
+  `Return the onboarding interview questions. Ask the user ONE at a time, starting with the
+goal of the memory system, and ask follow-ups for clarity. Turn each answer into a canonical memory.`,
+  {},
+  async () => ({
+    content: [{ type: 'text' as const, text: INTERVIEW_QUESTIONS.map((q, i) => `${i + 1}. ${q}`).join('\n') }],
+  })
+);
+
 // --- Task Management Tools ---
 
 server.tool(

package/src/onboard/index.ts

@@ -0,0 +1,298 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `awm onboard` — warm-start a cold memory store from a project's own knowledge.
+ *
+ * The cold-start problem: a fresh AWM store knows nothing, so recall returns
+ * nothing until enough interactions accumulate. Onboarding derives a seed set of
+ * memories up front — from documentation, the repository, and a short interview —
+ * so an agent can be useful on a project from the first turn.
+ *
+ * Design decisions (what makes this good vs. a vector-DB doc-dump):
+ *  - It emits an **`awm import`-compatible file**, not direct writes — so it reuses
+ *    the importer, and the file is the human review/edit surface ("make changes
+ *    based on what's needed"). Flow: onboard -> review/edit -> `awm import`.
+ *  - It extracts **atomic, recall-shaped memories** (concept = the fact/heading,
+ *    content = the supporting text, tags = proj/topic/origin), not raw chunks.
+ *  - Seed facts from the owner's own docs are **canonical** — they bypass the
+ *    salience filter (which is designed to reject low-novelty observations and
+ *    would otherwise silently drop half the seed).
+ *  - It is **model-free** (this tier): deterministic Markdown/section + repo
+ *    structure extraction, no API keys — preserving AWM's "everything local"
+ *    property. An LLM-assisted extractor + live interview layer on top of this.
+ *  - Ids are content-hashed, so re-running on changed docs is **idempotent**
+ *    (import `--dedupe` drops unchanged rows; edited sections become new rows).
+ *
+ * The interview is emitted as questions in the review file (a model-free tier
+ * can't converse); answering them and re-running folds the answers into the seed.
+ * The anchor question is deliberately "What is the goal of this memory system?" —
+ * the answer shapes what knowledge is worth keeping.
+ */
+import { readFileSync, readdirSync, existsSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, join, extname, basename, relative, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+
+export interface OnboardMemory {
+  id: string;
+  agent_id: string;
+  concept: string;
+  content: string;
+  tags: string[];
+  confidence: number;
+  salience: number;
+  memory_class: 'canonical' | 'working';
+}
+
+export interface OnboardPack {
+  version: string;
+  kind: 'awm-onboard-pack';
+  project: string;
+  generated_for: string; // agent id
+  purpose: string | null; // answer to "what is the goal of this memory system?"
+  memories: OnboardMemory[];
+  questions: string[];
+}
+
+export interface OnboardOptions {
+  /** Files/dirs to scan for documentation (Markdown/text). */
+  docs: string[];
+  /** Repo root to derive structural memories from (package.json, README, layout). */
+  repo?: string;
+  project: string;
+  /** Target agent id stamped on every seed memory. */
+  agentId: string;
+  /** The project/memory-system goal (the anchor interview answer), if provided. */
+  purpose?: string;
+}
+
+const DOC_EXT = new Set(['.md', '.mdx', '.markdown', '.txt', '.rst']);
+const MAX_CONTENT = 1200; // cap a section; the lead usually carries the fact
+
+/** The high-value intake — what a domain expert would want captured that docs miss. */
+export const INTERVIEW_QUESTIONS: string[] = [
+  'What is the goal of this memory system — what should the agent get better at over time?',
+  'What is the one-sentence description of this project and who it is for?',
+  'What is the tech stack and the non-obvious tools/services it depends on?',
+  'What naming conventions, patterns, or house style must the agent follow?',
+  'What decisions are settled (and should NOT be re-litigated)?',
+  'Who are the key people/systems, and how are they referred to?',
+  'What are the known gotchas, footguns, or "here be dragons" areas?',
+  'What does "done right" look like here — the definition of quality?',
+];
+
+/**
+ * The onboarding skill — a procedure stored AS a canonical memory so a host agent
+ * (Codex, Claude Code, MWA) can *recall* it and run the interview itself. This is
+ * how the "LLM-assisted" tier works without AWM ever calling a model: the agent
+ * that's already there is the brain; AWM provides the procedure + the tools.
+ * Seeded by `awm setup`; recalled on a cold store (see the restore nudge).
+ */
+export const ONBOARD_SKILL = {
+  concept: 'Skill: onboard a new project (warm-start protocol)',
+  content: [
+    'When the memory store is empty or you are new to this project, warm-start it before doing other work:',
+    '1. Call the `onboard_scan` tool with the docs dir + repo path to get candidate memories (a deterministic scan — real file contents, not guesses).',
+    '2. Refine each candidate into an ATOMIC, recall-shaped memory: lead with the fact, keep it to one idea, and include concrete identifiers (file paths, table columns, function names, ticket IDs). Split fat sections into 2-3 crisp facts; drop noise.',
+    '3. Run the interview: call `onboard_questions`, then ask the user ONE question at a time starting with "What is the goal of this memory system?". Ask follow-ups for clarity when an answer is vague.',
+    '4. Propose the memory set you intend to save and get the user\'s confirmation (edit/drop as they direct).',
+    '5. Save each with `memory_write`, memory_class="canonical", tagged with project + topic + source. Stamp facts from the owner\'s own docs as verified/observed; mark your own inferences lower.',
+    'Result: recall is useful from the next turn on. Re-run when the docs change to keep the seed fresh (supersede, don\'t duplicate).',
+  ].join('\n'),
+  tags: ['topic=skill', 'name=onboard', 'src=onboarding', 'intent=context'],
+};
+
+function slugify(s: string): string {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+}
+
+/** Deterministic short id from content → idempotent re-runs. */
+function mkId(seed: string): string {
+  return 'onb-' + createHash('sha1').update(seed).digest('hex').slice(0, 16);
+}
+
+function clean(text: string): string {
+  const t = text
+    .replace(/```[\s\S]*?```/g, (m) => m.length > 300 ? '[code block]' : m) // drop huge code fences
+    .replace(/\r/g, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+  return t.length > MAX_CONTENT ? t.slice(0, MAX_CONTENT).trimEnd() + ' …' : t;
+}
+
+function mkMemory(
+  concept: string, content: string, topic: string, origin: string, opts: OnboardOptions,
+): OnboardMemory | null {
+  const c = clean(content);
+  const title = concept.trim();
+  // Skip empties and thin headings with no supporting prose.
+  if (!title || c.length < 24) return null;
+  return {
+    id: mkId(`${opts.agentId}::${title}::${c}`),
+    agent_id: opts.agentId,
+    concept: title.slice(0, 120),
+    content: c,
+    tags: [`proj=${opts.project}`, `topic=${topic}`, 'src=onboarding', `origin=${origin}`, 'intent=context'],
+    confidence: 0.7, // observed — derived from the owner's own docs
+    salience: 0.7, // canonical floor
+    memory_class: 'canonical',
+  };
+}
+
+/**
+ * Split a Markdown/text doc into atomic memories, one per heading section.
+ * A section's memory is (heading, the prose under it up to the next heading).
+ * Untitled preamble before the first heading is captured as an "Overview".
+ */
+export function scanMarkdown(text: string, origin: string, opts: OnboardOptions): OnboardMemory[] {
+  const out: OnboardMemory[] = [];
+  const lines = text.replace(/\r/g, '').split('\n');
+  let heading = '';
+  let buf: string[] = [];
+  const flush = () => {
+    const body = buf.join('\n').trim();
+    const concept = heading || `${basename(origin)} — overview`;
+    const topic = slugify(heading || basename(origin, extname(origin)));
+    const mem = mkMemory(concept, body, topic || 'doc', origin, opts);
+    if (mem) out.push(mem);
+    buf = [];
+  };
+  for (const line of lines) {
+    const h = /^(#{1,3})\s+(.*)$/.exec(line);
+    if (h) { flush(); heading = h[2].trim(); }
+    else buf.push(line);
+  }
+  flush();
+  return out;
+}
+
+/** Recursively collect documentation files under the given paths. */
+function collectDocs(paths: string[]): string[] {
+  const files: string[] = [];
+  const walk = (p: string) => {
+    if (!existsSync(p)) return;
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      if (/node_modules|\.git|dist|build/.test(p)) return;
+      for (const e of readdirSync(p)) walk(join(p, e));
+    } else if (DOC_EXT.has(extname(p).toLowerCase())) {
+      files.push(p);
+    }
+  };
+  for (const p of paths) walk(resolve(p));
+  return files;
+}
+
+/** Derive structural memories from a repository (package.json, README, layout). */
+export function scanRepo(root: string, opts: OnboardOptions): OnboardMemory[] {
+  const out: OnboardMemory[] = [];
+  const r = resolve(root);
+  // package.json → stack + scripts
+  const pkgPath = join(r, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).slice(0, 25);
+      const scripts = Object.keys(pkg.scripts ?? {});
+      const parts = [
+        pkg.description ? `${pkg.name}: ${pkg.description}.` : `Project package: ${pkg.name} (v${pkg.version ?? '?'}).`,
+        deps.length ? `Key dependencies: ${deps.join(', ')}.` : '',
+        scripts.length ? `npm scripts: ${scripts.join(', ')}.` : '',
+      ].filter(Boolean).join(' ');
+      const m = mkMemory(`Project stack — ${pkg.name}`, parts, 'stack', 'package.json', opts);
+      if (m) out.push(m);
+    } catch { /* malformed package.json — skip */ }
+  }
+  // Top-level layout → a structure memory
+  try {
+    const entries = readdirSync(r)
+      .filter((e) => !/^\.|node_modules|dist|build/.test(e))
+      .filter((e) => { try { return statSync(join(r, e)).isDirectory(); } catch { return false; } });
+    if (entries.length) {
+      const m = mkMemory(
+        `Repository layout — ${opts.project}`,
+        `Top-level directories: ${entries.map((e) => `${e}/`).join(', ')}.`,
+        'layout', 'repo-structure', opts,
+      );
+      if (m) out.push(m);
+    }
+  } catch { /* unreadable root — skip */ }
+  return out;
+}
+
+/** Assemble a reviewable, `awm import`-compatible pack from the sources. */
+export function buildPack(opts: OnboardOptions): OnboardPack {
+  const memories: OnboardMemory[] = [];
+
+  // The anchor: the goal of the memory system, if the owner supplied it.
+  if (opts.purpose && opts.purpose.trim()) {
+    const g = mkMemory(
+      `Goal of this memory system — ${opts.project}`, opts.purpose.trim(), 'goal', 'interview', opts,
+    );
+    if (g) memories.push(g);
+  }
+
+  for (const file of collectDocs(opts.docs)) {
+    const rel = opts.repo ? relative(resolve(opts.repo), file) : basename(file);
+    try {
+      memories.push(...scanMarkdown(readFileSync(file, 'utf-8'), rel.replace(/\\/g, '/'), opts));
+    } catch { /* unreadable file — skip */ }
+  }
+  if (opts.repo) memories.push(...scanRepo(opts.repo, opts));
+
+  // Dedup by content-hash id (idempotent across re-runs and overlapping sources).
+  const seen = new Set<string>();
+  const deduped = memories.filter((m) => (seen.has(m.id) ? false : (seen.add(m.id), true)));
+
+  return {
+    version: '1',
+    kind: 'awm-onboard-pack',
+    project: opts.project,
+    generated_for: opts.agentId,
+    purpose: opts.purpose?.trim() || null,
+    memories: deduped,
+    questions: INTERVIEW_QUESTIONS,
+  };
+}
+
+/** A human-readable review surface: the owner edits this understanding, then imports the JSON. */
+export function renderReview(pack: OnboardPack): string {
+  const lines: string[] = [];
+  lines.push(`# Onboarding review — ${pack.project}`);
+  lines.push('');
+  lines.push(`Generated ${pack.memories.length} candidate memories for agent \`${pack.generated_for}\`.`);
+  lines.push('Edit/delete below as needed, then import the JSON pack:');
+  lines.push('');
+  lines.push('```');
+  lines.push(`awm import <pack>.json --db <path> --dedupe`);
+  lines.push('```');
+  lines.push('');
+  lines.push('## Interview — answer these and re-run to enrich the seed');
+  lines.push('');
+  for (const q of pack.questions) lines.push(`- [ ] ${q}`);
+  lines.push('');
+  lines.push('## Candidate memories');
+  lines.push('');
+  for (const m of pack.memories) {
+    lines.push(`### ${m.concept}`);
+    lines.push(`*${m.tags.join(' · ')}* — class=${m.memory_class}`);
+    lines.push('');
+    lines.push(m.content);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * CLI entry: scan → write the import pack (JSON) + a review file (Markdown).
+ * Does not touch a store — the produced JSON is fed to `awm import`.
+ */
+export function runOnboard(opts: OnboardOptions & { outDir: string }): { packPath: string; reviewPath: string; count: number } {
+  const pack = buildPack(opts);
+  mkdirSync(opts.outDir, { recursive: true });
+  const base = `onboard-${slugify(opts.project) || 'project'}`;
+  const packPath = join(opts.outDir, `${base}.pack.json`);
+  const reviewPath = join(opts.outDir, `${base}.review.md`);
+  writeFileSync(packPath, JSON.stringify(pack, null, 2), 'utf-8');
+  writeFileSync(reviewPath, renderReview(pack), 'utf-8');
+  return { packPath, reviewPath, count: pack.memories.length };
+}

package/src/storage/factory.ts

@@ -39,7 +39,7 @@
 import { existsSync, statSync } from 'node:fs';
 import type { IEngramStore } from './store.js';
 
-export type StoreBackend = 'sqlite' | 'pglite';
+export type StoreBackend = 'sqlite' | 'pglite' | 'postgres';
 
 /**
  * Auto-detect the backend from on-disk state. Used when `AWM_STORE_BACKEND`
@@ -71,6 +71,7 @@ export function getConfiguredBackend(): StoreBackend {
     const normalized = raw.toLowerCase();
     if (normalized === 'pglite') return 'pglite';
     if (normalized === 'sqlite') return 'sqlite';
+    if (normalized === 'postgres') return 'postgres';
     console.warn(`Unknown AWM_STORE_BACKEND=${raw}; falling back to sqlite`);
     return 'sqlite';
   }
@@ -80,8 +81,11 @@ export function getConfiguredBackend(): StoreBackend {
 }
 
 export function getConfiguredPath(): string {
+  const backend = getConfiguredBackend();
+  // Postgres uses a connection URL, not an on-disk path.
+  if (backend === 'postgres') return process.env.AWM_DATABASE_URL ?? 'postgres://localhost:5432/awm';
   if (process.env.AWM_DB_PATH) return process.env.AWM_DB_PATH;
-  return getConfiguredBackend() === 'pglite' ? 'memory-pglite' : 'memory.db';
+  return backend === 'pglite' ? 'memory-pglite' : 'memory.db';
 }
 
 /**
@@ -132,7 +136,15 @@ export async function openStore(): Promise<{
   const backend = getConfiguredBackend();
   const path = getConfiguredPath();
 
-  warnIfBackendDisagreesWithDisk(backend, path);
+  // The on-disk mismatch warning only applies to file/dir backends.
+  if (backend !== 'postgres') warnIfBackendDisagreesWithDisk(backend, path);
+
+  if (backend === 'postgres') {
+    const { PostgresEngramStore } = await import('./postgres.js');
+    const store = new PostgresEngramStore(path);
+    await store.ready();
+    return { store: store as unknown as IEngramStore, backend, path };
+  }
 
   if (backend === 'pglite') {
     const { PGliteEngramStore } = await import('./pglite.js');

package/src/storage/index.ts

@@ -1,3 +1,3 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-export * from './sqlite.js';
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+export * from './sqlite.js';