memorix 1.4.5 → 1.4.6

package/docs/1.4.5-AGENT-AUTO-MEMORY-RESEARCH.md

@@ -0,0 +1,95 @@
+# Research: Claude Code Auto Memory and What Memorix Should Borrow
+
+> Status: research note (2026-08-14, against the 1.4.5 line). This document
+> records findings and direction; it is not a shipped feature and not a claim
+> that any item below is implemented.
+
+## Question
+
+Claude Code's Auto Memory gives a single agent a file-based, recallable
+workspace memory: `~/.claude/projects/<git-root>/memory/` with a `MEMORY.md`
+entrypoint index and typed memory files. What is the design, how does it
+compare with Memorix, and which parts are worth absorbing?
+
+## Sourcing caveat
+
+The mechanism-level details below come from community source-level analyses
+and third-party write-ups, not from an official Anthropic specification:
+
+- Source-level analysis of the memory system (`memdir`): project-memory.mdx
+  in a community Claude Code docs mirror
+  (https://github.com/claude-code-best/claude-code/blob/master/docs/context/project-memory.mdx)
+- Independent critical analysis:
+  https://dev.to/chen_zhang_bac430bc7f6b95/claude-codes-memory-4-layers-of-complexity-still-just-grep-and-a-200-line-cap-2kn9
+- Community adoption discussion:
+  https://developer.aliyun.com/article/1713756
+
+Treat feature-flag names (`KAIROS`, `TEAMMEM`) and thresholds as observed
+behavior of a moving target, not as stable contracts.
+
+## The design, in brief
+
+- Pure Markdown files, no database, no vector store. One directory per
+  sanitized Git root, shared across worktrees of that repository.
+- `MEMORY.md` is the entrypoint index: at most 200 lines AND 25 KB, one
+  `- [Title](file.md) — one-line hook` pointer per line, loaded into every
+  session. The knowledge lives in topic files, loaded on demand.
+- A closed four-type taxonomy (user / feedback / project / reference), each
+  type with explicit `<when_to_save>`, `<how_to_use>`, and `<body_structure>`
+  rules. Each memory file carries frontmatter whose `description` field is
+  written for the recall system, not for humans.
+- The core saving rule: only store information that cannot be derived from
+  the current project state. Code, file paths, and Git history are
+  re-derivable and do not belong in memory.
+- Recall is a lightweight model side-query that picks at most 5 relevant
+  memories from the manifest, with denoising for recently used tools and
+  dedup of already-surfaced files.
+- Memory is injected as a user-context message (prompt-cache friendly).
+- Drift defense is prompt-level: a memory that names a file, function, or
+  flag is a claim about the past — verify before recommending. An explicit
+  "ignore memory" instruction means proceed as if `MEMORY.md` were empty.
+- Consolidation ("dream") is time/volume-triggered, merging contradictions
+  and pruning stale entries. Long-running sessions may switch to append-only
+  daily logs that a later pass distills.
+- Security: the memory directory resolves only from user-level input
+  (environment override or a user setting). Project-level settings are
+  deliberately excluded from that resolution chain, so a hostile repository
+  cannot redirect memory storage to arbitrary paths.
+
+## Comparison with Memorix
+
+| Aspect | Claude Code Auto Memory | Memorix (1.4.5) |
+| --- | --- | --- |
+| Audience | One agent, one product | Any MCP/CLI/SDK/hooks agent, shared |
+| Storage | Markdown files | SQLite canonical store + Orama search |
+| Entry injection | Full index, fixed 200-line/25 KB cap | Task-lensed Workset, budget-governed |
+| Taxonomy | Closed 4 types | 11 observation types + reasoning + Git + long-term |
+| Recall | Paid model side-query (needs a key) | Local BM25 primary + bounded semantic fallback |
+| Drift defense | Prompt-level verify-before-use | Freshness, attribution guard, evidence governor |
+| Cleanup | Time/volume-triggered consolidation | Retention + dedup + consolidation pipeline |
+| Path security | User-level-only resolution | User-level-only by construction (env var only) |
+
+The critical review's complaint — memory trapped in one product's sandbox,
+no cross-agent sharing — is exactly the space Memorix occupies.
+
+## What Memorix should borrow (directions, not commitments)
+
+Shipped (2026-08-14, continuing on the 1.4.x line):
+1. **The "only store the underivable" rule, made explicit.** Now part of every
+   generated guidance file, with the dual-channel rule and the verify-before-use
+   / ignore semantics.
+2. **Dual-channel feedback.** Guidance now tells agents to record validated
+   approaches and explicit user confirmations, not only corrections.
+3. **Session-level dedup of already-surfaced memory.** `memorix_search`
+   demotes rows already shown in the same session (never removes them) and
+   remembers the surfaced set per session; measured 25% → 19% duplicate rate
+   with hits and budget unchanged.
+4. **Explicit ignore semantics.** Guidance now states the contract: an ignore
+   instruction means proceed as if memory were empty.
+5. **Keep the security boundary tested.** Pinned by
+   `tests/config/data-dir-boundary.test.ts`.
+
+Scoring lives in `tests/evaluation/session-replay-evaluation.test.ts`
+(retrieval) and `tests/evaluation/guidance-content.test.ts` (guidance); both
+are deterministic and offline. A future change to these behaviors must update
+the pinned scores only with a measured improvement.

package/docs/API_REFERENCE.md

@@ -223,7 +223,7 @@ Important inputs:
 - optional `relatedCommits`
 - optional `relatedEntities`
 - optional `visibility`: `project` (default), `personal`, or `team`
-- optional `longTerm`: an explicit source-backed long-term candidate with `kind` (`episodic`, `semantic`, or `procedural`), an optional `scope` (`project`, `user`, or `team`), tags, and applicability
+- optional `longTerm`: an explicit source-backed long-term record with `kind` (`episodic`, `semantic`, or `procedural`), an optional `scope` (`project`, `user`, or `team`), tags, and applicability
 
 Visibility controls who can retrieve a record through agent-facing memory
 tools. Normal memories default to `project`. `personal` and `team` writes
@@ -236,11 +236,15 @@ files, `memorix_store` returns without writing. Use `overrideReadOnly: true`
 only when the user explicitly asks to preserve a record during that task.
 
 `longTerm` is deliberately opt-in. It stores the normal Observation first, then
-creates a separate candidate with an evidence reference. Candidates are not
-inserted into a Task Workset. Review them with `memorix memory long-term
-list|show|qualify|approve|archive|supersede`. Source-derived entries remain
+creates a separate record with an evidence reference. Because an explicit
+request carries its own source evidence, the new record is auto-qualified on
+the spot and enters Task Worksets as durable context; approval remains an
+explicit operator review. Manage records with `memorix memory long-term
+list|show|approve|archive|supersede`. Source-derived entries remain
 project-bound; only a manual or user-confirmed `user + portable` record created
 through the CLI may cross local projects for the same local installation.
+Hook-captured and git-derived candidates stay in the candidate state until
+qualified.
 
 Example:
 
@@ -540,6 +544,21 @@ Use it to inspect:
 - stage timing
 - recent pipeline behavior
 
+### `memorix_audit_project`
+
+Scan the current project for observations that may have been written to the
+wrong project bucket — entities that appear exclusively in a different
+project. Read-only; nothing is changed.
+
+Available in the `full` tool profile (`MEMORIX_MODE=full` or `--mode full`).
+
+Important inputs:
+
+- optional `threshold` — minimum occurrences in another project to flag
+  (default: 2)
+
+Archive confirmed mis-attributed observations with `memorix_resolve`.
+
 ---
 
 ## 7. Skills and Promotion Tools

package/docs/CONFIGURATION.md

@@ -294,10 +294,24 @@ Server and dashboard behavior.
 
 Common keys:
 
-- `transport = "stdio"`
-- `port = 3211`
+- `transport = "stdio"` — advisory. An explicit `memorix serve-http` still
+  runs on HTTP and prints a notice; this key documents the intended mode.
+- `port = 3211` — default listener port for `memorix serve-http` when
+  `--port` is not given.
 - `dashboard = true`
-- `dashboard_port = 3210`
+- `dashboard_port = 3210` — default port for `memorix dashboard` when
+  `--port` is not given.
+
+### Reserved sections (parsed, not yet enforced)
+
+These sections exist so future releases do not need a config format change.
+Today no runtime behavior reads them; set them only as forward-looking notes.
+
+- `[team]` (`enabled`, `workspace_collection`) — coordination defaults.
+- `[hooks]` (`native_memcode`, `external_agents`) — hook bootstrap policy.
+- The former `mcpServers` key in `memorix.yml` was removed: no code ever
+  consumed it, and Memorix is not an MCP aggregator. Unknown keys are
+  ignored, so old files keep loading.
 
 ---
 

package/docs/SETUP.md

@@ -17,9 +17,9 @@ Common runtime entry points:
 
 | Entry | Use it for |
 | --- | --- |
-| `memorix setup --agent <agent> --global` | one-command user-level agent integration |
+| `memorix setup --agent <agent> --global` | one-command user-level agent integration; installs the stdio server with `--mode lite` so every tool taught in the generated guidance is actually reachable |
 | `memorix` CLI commands | direct workflows: setup, search/store, Git Memory, import/export, dashboard, diagnostics, orchestration, and automation |
-| `memorix serve` | stdio MCP server for IDEs and coding agents; defaults to a compact `micro` tool profile |
+| `memorix serve` | stdio MCP server for IDEs and coding agents; defaults to a compact `micro` tool profile when launched manually |
 | `memorix background start` | long-lived HTTP MCP service plus dashboard |
 | `memorix serve-http --port 3211` | foreground HTTP MCP for debugging or supervised launches |
 | `memorix` / `memcode` | bundled terminal agent that uses the same Memorix memory pool |
@@ -151,7 +151,9 @@ memorix serve
 
 Use this when your agent only needs a raw local stdio MCP process or you are debugging a manual config. The agent starts `memorix serve` and communicates with it over stdio.
 
-The stdio server defaults to `--mode micro`, which exposes 9 high-signal tools so agent context is not crowded by rarely used schemas. Use `memorix serve --mode lite` for the extended solo memory surface, `--mode team` for coordination tools, or `--mode full` for advanced and MCP Memory compatibility tools.
+A bare `memorix serve` defaults to `--mode micro`, which exposes 9 high-signal tools so agent context is not crowded by rarely used schemas. Use `memorix serve --mode lite` for the extended solo memory surface, `--mode team` for coordination tools, or `--mode full` for advanced and MCP Memory compatibility tools.
+
+`memorix setup` writes `--mode lite` into the installed MCP config: the generated guidance teaches the extended surface (sessions, timeline, reasoning, retention), so the installed server must actually expose it. Override with `MEMORIX_MODE` if you prefer a different profile.
 
 Generic stdio MCP config:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,

package/plugins/antigravity/memorix/mcp_config.json

@@ -3,7 +3,9 @@
     "memorix": {
       "command": "memorix",
       "args": [
-        "serve"
+        "serve",
+        "--mode",
+        "lite"
       ]
     }
   }

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/claude/memorix/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "memorix": {
       "command": "memorix",
-      "args": ["serve"],
+      "args": ["serve", "--mode", "lite"],
       "alwaysLoad": true
     }
   }

package/plugins/codebuddy/memorix/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Local-first project memory for CodeBuddy Code and other coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codebuddy/memorix/.mcp.json

@@ -3,7 +3,7 @@
     "memorix": {
       "type": "stdio",
       "command": "memorix",
-      "args": ["serve"]
+      "args": ["serve", "--mode", "lite"]
     }
   }
 }

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "memorix": {
       "command": "memorix",
-      "args": ["serve"]
+      "args": ["serve", "--mode", "lite"]
     }
   }
 }

package/plugins/copilot/memorix/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "memorix": {
       "command": "memorix",
-      "args": ["serve"]
+      "args": ["serve", "--mode", "lite"]
     }
   }
 }

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,11 +1,13 @@
 {
   "name": "memorix",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "mcpServers": {
     "memorix": {
       "command": "memorix",
       "args": [
-        "serve"
+        "serve",
+        "--mode",
+        "lite"
       ]
     }
   },

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/openclaw/memorix/.mcp.json

@@ -3,7 +3,9 @@
     "memorix": {
       "command": "memorix",
       "args": [
-        "serve"
+        "serve",
+        "--mode",
+        "lite"
       ]
     }
   }

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/AVIDS2/memorix",
     "source": "github"
   },
-  "version": "1.4.5",
+  "version": "1.4.6",
   "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.4.5",
+      "version": "1.4.6",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/commands/dashboard.ts

@@ -22,8 +22,8 @@ export default defineCommand({
     args: {
         port: {
             type: 'string',
-            description: 'Port to run the dashboard on (default: 3210)',
-            default: '3210',
+            description: 'Port to run the dashboard on (default: [server].dashboardPort or 3210)',
+            required: false,
         },
     },
     run: async ({ args }) => {
@@ -31,13 +31,24 @@ export default defineCommand({
         const { getProjectDataDir } = await import('../../store/persistence.js');
         const { startDashboard } = await import('../../dashboard/server.js');
 
+        // The [server].dashboardPort config is a real default source; the
+        // explicit --port flag always wins.
+        let configuredDashboardPort: number | undefined;
+        try {
+            const { getServerConfig } = await import('../../config.js');
+            const serverConfig = getServerConfig();
+            configuredDashboardPort = typeof serverConfig.dashboardPort === 'number'
+                ? serverConfig.dashboardPort
+                : undefined;
+        } catch { /* config files are optional */ }
+
         const project = detectProject();
         if (!project) {
             console.error('Memorix requires a git repo to establish project identity. Run `git init` in this workspace first.');
             process.exit(1);
         }
         const dataDir = await getProjectDataDir(project.id);
-        const port = parseTcpPortOrReport(args.port as string | undefined, 3210);
+        const port = parseTcpPortOrReport(args.port as string | undefined, configuredDashboardPort ?? 3210);
         if (port === undefined) {
             process.exitCode = 1;
             return;

package/src/cli/commands/ingest-commit.ts

@@ -7,6 +7,37 @@
 
 import { defineCommand } from 'citty';
 import * as p from '@clack/prompts';
+import type { CommitInfo } from '../../git/extractor.js';
+
+export interface GitIngestPolicyInput {
+  ingestOnCommit?: boolean;
+  maxDiffSize?: number;
+}
+
+/**
+ * The documented git policy settings are real gates, not display-only facts:
+ * `ingest_on_commit = false` disables post-commit ingestion, and
+ * `max_diff_size` caps how much diff content is captured into the narrative.
+ */
+export function applyGitIngestPolicy(
+  commit: CommitInfo,
+  policy: GitIngestPolicyInput,
+): { skip: boolean; reason?: string; diffSummary: string } {
+  if (policy.ingestOnCommit === false) {
+    return {
+      skip: true,
+      reason: 'ingest_on_commit is disabled',
+      diffSummary: commit.diffSummary,
+    };
+  }
+  const cap = policy.maxDiffSize;
+  return {
+    skip: false,
+    diffSummary: typeof cap === 'number' && Number.isFinite(cap)
+      ? commit.diffSummary.slice(0, Math.max(0, Math.floor(cap)))
+      : commit.diffSummary,
+  };
+}
 
 export default defineCommand({
   meta: {
@@ -42,13 +73,26 @@ export default defineCommand({
     if (!auto) p.intro(`Ingest commit: ${ref}`);
 
     try {
+      const { getGitConfig } = await import('../../config.js');
+      const gitCfg = getGitConfig();
       const { getCommitInfo, ingestCommit } = await import('../../git/extractor.js');
-      const commit = getCommitInfo(cwd, ref);
+      const commit = getCommitInfo(cwd, ref, gitCfg.maxDiffSize ?? 500);
+
+      // The documented ingest_on_commit gate: post-commit execution stops
+      // here when disabled. An explicit manual run always proceeds.
+      const policy = applyGitIngestPolicy(commit, {
+        ingestOnCommit: gitCfg.ingestOnCommit,
+        maxDiffSize: gitCfg.maxDiffSize,
+      });
+      if (policy.skip && auto) {
+        console.error(`[memorix] Skipped ${commit.shortHash}: ${policy.reason}`);
+        process.exit(0);
+        return;
+      }
+      commit.diffSummary = policy.diffSummary;
 
       // Noise filter: skip low-value commits (typo, format, lockfile, merge, etc.)
       const { shouldFilterCommit } = await import('../../git/noise-filter.js');
-      const { getGitConfig } = await import('../../config.js');
-      const gitCfg = getGitConfig();
       const filterResult = shouldFilterCommit(commit, {
         skipMergeCommits: gitCfg.skipMergeCommits,
         excludePatterns: gitCfg.excludePatterns,

package/src/cli/commands/memory.ts

@@ -467,6 +467,7 @@ export default defineCommand({
             createManualLongTermMemory,
             getLongTermMemoryDetail,
             listLongTermMemories,
+            maybeAutoQualifyLongTermMemory,
             promoteObservationToLongTermMemory,
             qualifyLongTermMemory,
             supersedeLongTermMemory,
@@ -545,9 +546,15 @@ export default defineCommand({
                 portability: portability(),
                 reader: longTermReader,
               });
+              // Operator-written records carry their own source evidence.
+              const qualified = await maybeAutoQualifyLongTermMemory({
+                dataDir,
+                id: result.memory.id,
+                source: 'manual',
+              });
               emitResult(
-                { project, ...result },
-                `Created long-term memory candidate ${result.memory.id}. Qualify it after checking its evidence.`,
+                { project, ...result, memory: qualified ?? result.memory },
+                `Created long-term memory ${result.memory.id}.`,
                 asJson,
               );
               return;
@@ -576,9 +583,15 @@ export default defineCommand({
                 applicability: asStringArg(args.applicability),
                 reader: longTermReader,
               });
+              // An explicit promote request carries its own source evidence.
+              const qualified = await maybeAutoQualifyLongTermMemory({
+                dataDir,
+                id: result.memory.id,
+                sourceDetail: 'explicit',
+              });
               emitResult(
-                { project, sourceObservationId: observation.id, ...result },
-                `Promoted observation #${observation.id} to long-term memory candidate ${result.memory.id}.`,
+                { project, sourceObservationId: observation.id, ...result, memory: qualified ?? result.memory },
+                `Promoted observation #${observation.id} to long-term memory ${result.memory.id}.`,
                 asJson,
               );
               return;

package/src/cli/commands/purge.ts

@@ -0,0 +1,120 @@
+/**
+ * CLI Command: memorix purge
+ *
+ * Retire memories from retrieval. Project-scoped by default; --all covers
+ * every project. Observations and long-term records are archived (never
+ * hard-deleted) so the audit trail survives. Refuses to run outside a
+ * terminal without --yes.
+ */
+
+import { defineCommand } from 'citty';
+import { detectProject } from '../../project/detector.js';
+import { getProjectDataDir } from '../../store/persistence.js';
+
+export default defineCommand({
+  meta: {
+    name: 'purge',
+    description: 'Retire memories from retrieval (current project by default, --all for every project)',
+  },
+  args: {
+    all: {
+      type: 'boolean',
+      description: 'Purge every project instead of the current one',
+      default: false,
+    },
+    yes: {
+      type: 'boolean',
+      description: 'Skip the interactive confirmation',
+      default: false,
+    },
+    json: {
+      type: 'boolean',
+      description: 'Emit a machine-readable result',
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const purgeAll = Boolean(args.all);
+    const yes = Boolean(args.yes);
+    const asJson = Boolean(args.json);
+
+    // Confirmation gate first: a destructive wipe never proceeds in a
+    // non-interactive shell without an explicit --yes.
+    if (!yes && !process.stdin.isTTY) {
+      console.error('[ERROR] Non-interactive environment. Add --yes to confirm.');
+      console.error('[ERROR] Refusing to purge memories without confirmation.');
+      process.exitCode = 1;
+      return;
+    }
+    if (!yes) {
+      const readline = await import('node:readline');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const question = purgeAll
+        ? 'Retire ALL memories from every project? (y/N) '
+        : 'Retire all memories for this project? (y/N) ';
+      const answer = await new Promise<string>((resolve) => rl.question(question, resolve));
+      rl.close();
+      if (answer.trim().toLowerCase() !== 'y') {
+        console.log('Cancelled.');
+        return;
+      }
+    }
+
+    let projectId: string | null = null;
+    if (!purgeAll) {
+      const project = detectProject();
+      if (!project) {
+        console.error('[ERROR] No .git found — run from a project directory or pass --all.');
+        process.exitCode = 1;
+        return;
+      }
+      projectId = project.id;
+    }
+
+    const dataDir = await getProjectDataDir(projectId ?? '');
+    const { initObservationStore } = await import('../../store/obs-store.js');
+    const { getAllObservations, resolveObservations } = await import('../../memory/observations.js');
+    const { withFreshIndex } = await import('../../memory/freshness.js');
+    await initObservationStore(dataDir);
+
+    const observations = await withFreshIndex(() => getAllObservations());
+    const target = purgeAll ? observations : observations.filter((o) => o.projectId === projectId);
+    const ids = target
+      .map((o) => o.id)
+      .filter((id): id is number => typeof id === 'number');
+    const archived = ids.length > 0
+      ? (await resolveObservations(ids, 'archived')).resolved.length
+      : 0;
+
+    const { LongTermMemoryStore } = await import('../../memory/long-term-store.js');
+    const { archiveLongTermMemory } = await import('../../memory/long-term.js');
+    const longTermStore = new LongTermMemoryStore();
+    await longTermStore.init(dataDir);
+    let longTermArchived = 0;
+    for (const memory of longTermStore.list()) {
+      if (memory.state === 'archived' || memory.state === 'superseded') continue;
+      if (!purgeAll && memory.originProjectId !== projectId) continue;
+      try {
+        await archiveLongTermMemory({
+          dataDir,
+          id: memory.id,
+          reason: purgeAll ? 'purge --all' : 'purge (project) ' + (projectId ?? ''),
+        });
+        longTermArchived += 1;
+      } catch { /* already inactive */ }
+    }
+
+    const result = {
+      scope: purgeAll ? 'all' : projectId,
+      observationsArchived: archived,
+      longTermArchived,
+    };
+    if (asJson) {
+      console.log(JSON.stringify(result));
+    } else {
+      console.log(
+        `[OK] Purged ${purgeAll ? 'all projects' : result.scope}: archived ${archived} observations and ${longTermArchived} long-term memories.`,
+      );
+    }
+  },
+});