memorix 1.2.9 → 1.3.0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "memorix",
-  "version": "1.2.9",
+  "mcpName": "io.github.AVIDS2/memorix",
+  "version": "1.3.0",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,
@@ -33,6 +34,7 @@
   "files": [
     "dist",
     "src",
+    "server.json",
     "!src/**/*.js",
     "!src/**/*.js.map",
     "!src/**/*.d.ts",
@@ -63,9 +65,12 @@
     "test:e2e": "vitest run tests/e2e/",
     "benchmark:codegraph": "node scripts/benchmark-codegraph-provider.cjs",
     "benchmark:retrieval": "npm run build && node scripts/benchmark-retrieval.mjs",
+    "generate:star-history": "node scripts/generate-star-history.mjs",
+    "sync:mcp-registry": "node scripts/sync-mcp-registry-manifest.mjs",
+    "check:mcp-registry": "node scripts/check-mcp-registry-manifest.mjs",
     "audit:pi-upstream": "node scripts/pi-upstream-audit.mjs",
     "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run sync:mcp-registry && npm run check:mcp-registry && npm run build && npm test"
   },
   "keywords": [
     "mcp",

package/plugins/antigravity/memorix/rules/memorix.md

@@ -9,6 +9,8 @@ Use Memorix when prior workspace context, decisions, fixes, or handoff state wou
 - Use `memorix_search` for focused lookup.
 - Use `memorix_detail` before relying on a specific memory.
 - Use `memorix_store` for durable workspace knowledge.
+- Use `longTerm` on `memorix_store` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Use `memorix_store_reasoning` for the reason behind a technical decision.
 - Use `memorix_resolve` when completed or outdated memories should stop surfacing.
 

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.2.9",
+  "version": "1.3.0",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/claude/memorix/skills/memorix-memory/SKILL.md

@@ -17,6 +17,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -41,4 +42,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

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

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

package/plugins/codex/memorix/skills/memorix-memory/SKILL.md

@@ -18,6 +18,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -42,4 +43,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

package/plugins/copilot/memorix/plugin.json

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

package/plugins/copilot/memorix/skills/memorix-memory/SKILL.md

@@ -18,6 +18,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -42,4 +43,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

package/plugins/cursor/memorix/skills/memorix-memory/SKILL.md

@@ -18,6 +18,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -42,4 +43,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

package/plugins/gemini/memorix/GEMINI.md

@@ -11,6 +11,8 @@ Use Memorix when prior workspace context, decisions, fixes, or handoff state wou
 - Use `memorix_search` for focused lookup.
 - Use `memorix_detail` before relying on a specific memory.
 - Use `memorix_store` for durable workspace knowledge.
+- Use `longTerm` on `memorix_store` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Use `memorix_store_reasoning` for the reason behind a technical decision.
 - Use `memorix_resolve` when completed or outdated memories should stop surfacing.
 

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

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "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.2.9",
+  "version": "1.3.0",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

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

package/plugins/pi/memorix/skills/memorix-memory/SKILL.md

@@ -18,6 +18,7 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Need the full source for a search hit | `memorix_detail` | `memorix memory detail --id <id>` |
 | Need the sequence around one memory | `memorix_timeline` | `memorix memory timeline --id <id>` |
 | Learned reusable project knowledge | `memorix_store` | `memorix memory store --type <type> --entity <name> --title "<title>" "<text>"` |
+| Stable source-backed fact or procedure needing long-term review | `memorix_store` with `longTerm` | `memorix memory long-term qualify|approve --id <id> --reason "..."` |
 | Task or bug is complete/outdated | `memorix_resolve` | `memorix memory resolve --ids <ids>` |
 
 ## Search Rules
@@ -42,4 +43,6 @@ Use Memorix as the shared memory layer for the active workspace when Memorix too
 | Accepted compromise | `trade-off` |
 
 - Use concise titles, stable entity names, relevant `filesModified`, and `topicKey` for evolving topics.
+- Use `longTerm` only for a stable fact, reusable procedure, or completed episode that merits explicit review. It creates a candidate, not live context; keep the default project scope and do not use it for routine updates.
+- A `user` + `portable` durable memory in a task brief is intentionally reusable across projects. When it matches the task, use it as background even if it originated elsewhere; it is not a current-project fact. Expand it only when needed with `memorix_detail` and `typedRefs: ["durable:<id>"]`, stating the missing fact as `purpose`.
 - Do not store secrets, credentials, raw private transcripts, trivial commands, or routine file reads.

package/server.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.AVIDS2/memorix",
+  "title": "Memorix",
+  "description": "Local-first persistent project memory for AI coding agents across MCP clients and sessions.",
+  "repository": {
+    "url": "https://github.com/AVIDS2/memorix",
+    "source": "github"
+  },
+  "version": "1.3.0",
+  "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
+  "icons": [
+    {
+      "src": "https://raw.githubusercontent.com/AVIDS2/memorix/main/assets/logo.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "1024x1024"
+      ]
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "memorix",
+      "version": "1.3.0",
+      "runtimeHint": "npx",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "serve"
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/src/cli/command-guide.ts

@@ -15,8 +15,16 @@ const GUIDES: Record<string, CliCommandGuide> = {
       'memorix memory resolve --ids 42,43 [--status resolved|archived]',
       'memorix memory consolidate --action preview|execute',
       'memorix memory promote --ids 42,43 [--trigger "..."] [--instruction "..."]',
+      'memorix memory long-term list [--all]',
+      'memorix memory long-term add --kind semantic --scope user --portability portable --title "..." --text "..." [--tags "..."] [--applicability "..."]',
+      'memorix memory long-term promote --from-observation 42 --kind procedural --scope project',
+      'memorix memory long-term qualify|approve|archive --id <id> --reason "..."',
+      'memorix memory long-term supersede --id <old-id> --superseded-by <qualified-id> --reason "..."',
+    ],
+    notes: [
+      'Personal and team visibility require `memorix identity join` or `memorix identity use` first.',
+      'Candidates never enter a task Workset. Only manual or user-confirmed `user + portable` memory may cross local projects.',
     ],
-    notes: ['Personal and team visibility require `memorix identity join` or `memorix identity use` first.'],
   },
   identity: {
     summary: 'Select the active local actor for private memory and coordination commands.',

package/src/cli/commands/agent-integrations.ts

@@ -12,6 +12,7 @@ import {
   getSetupAgentTargets,
   installPluginPackage,
   installMcpConfig,
+  migrateLegacyCodexIntegration,
   tryInstallCodexPlugin,
   type McpConfigAgent,
 } from './setup.js';
@@ -228,7 +229,7 @@ function asRecordArray(value: unknown): JsonRecord[] {
 }
 
 function codexPluginPath(): string {
-  return `${homedir()}/.codex/plugins/${CODEX_PLUGIN_NAME}`;
+  return `${homedir()}/plugins/${CODEX_PLUGIN_NAME}`;
 }
 
 function codexPluginMcpPath(): string {
@@ -254,7 +255,10 @@ function isMemorixCodexPlugin(value: JsonRecord): boolean {
 
 export function parseCodexPluginList(output: string): AgentPluginCheck['runtime'] | null {
   try {
-    const parsed = asRecord(JSON.parse(output));
+    const start = output.indexOf('{');
+    const end = output.lastIndexOf('}');
+    if (start < 0 || end < start) return null;
+    const parsed = asRecord(JSON.parse(output.slice(start, end + 1)));
     if (!parsed) return null;
     const entries = [...asRecordArray(parsed.installed), ...asRecordArray(parsed.available)];
     const plugin = entries.find(isMemorixCodexPlugin);
@@ -407,7 +411,7 @@ async function inspectCodexMarketplace(): Promise<AgentPluginCheck> {
 
   const source = asRecord(entry.source);
   const sourcePath = typeof source?.path === 'string' ? source.path : '';
-  const issues = source?.source === 'local' && normalizeMarketplacePath(sourcePath) === '.codex/plugins/memorix'
+  const issues = source?.source === 'local' && normalizeMarketplacePath(sourcePath) === 'plugins/memorix'
     ? []
     : ['codex-marketplace-entry-stale'];
   return {
@@ -1060,9 +1064,11 @@ export async function repairAgentIntegrations(options: {
         } else {
           if (!options.dry) {
             await installPluginPackage({ agent: 'codex' });
-            if (needsInstall) {
-              const install = tryInstallCodexPlugin();
-              if (!install.ok) skipped.push('codex:plugin:global:install-pending');
+            const install = tryInstallCodexPlugin();
+            if (install.ok) {
+              await migrateLegacyCodexIntegration({ projectRoot });
+            } else {
+              skipped.push('codex:plugin:global:install-pending');
             }
           }
           changed.push('codex:plugin:global');

package/src/cli/commands/codegraph.ts

@@ -217,6 +217,7 @@ export default defineCommand({
             ...(external.caution
               ? { runtimeCautions: [{ kind: 'external-codegraph-fallback' as const, message: external.caution }] }
               : {}),
+            reader,
           });
           emitResult({ project, pack, providerQuality: external.quality }, buildContextPackPrompt(pack), asJson);
           return;

package/src/cli/commands/memory.ts

@@ -51,17 +51,30 @@ export default defineCommand({
     instruction: { type: 'string', description: 'Custom instruction for promoted mini-skills' },
     tags: { type: 'string', description: 'Comma-separated extra tags for promoted mini-skills' },
     skillId: { type: 'string', description: 'Mini-skill ID for list/delete actions' },
+    kind: { type: 'string', description: 'Long-term memory kind: episodic, semantic, or procedural' },
+    scope: { type: 'string', description: 'Long-term memory scope: project, user, or team' },
+    portability: { type: 'string', description: 'Long-term memory portability: project-bound or portable' },
+    applicability: { type: 'string', description: 'When a long-term memory applies' },
+    fromObservation: { type: 'string', description: 'Observation ID to promote into long-term memory' },
+    supersededBy: { type: 'string', description: 'Qualified or approved long-term memory that replaces the current record' },
+    'superseded-by': { type: 'string', description: 'Kebab-case alias for --supersededBy' },
+    reason: { type: 'string', description: 'Evidence review reason for qualify, approve, or archive' },
+    all: { type: 'boolean', description: 'Include archived and superseded long-term memories in list output' },
     json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
   },
   run: async ({ args }) => {
     const action = (args._ as string[])?.[0] || '';
     const positional = ((args._ as string[]) ?? []).slice(1);
+    const longTermAction = action === 'long-term'
+      ? (positional[0] || (args.action as string | undefined) || 'list').trim().toLowerCase()
+      : undefined;
     const asJson = !!args.json;
 
     try {
       const readOnlyActions = new Set(['', 'search', 'graph-context', 'recent', 'suggest-topic-key', 'detail', 'timeline']);
       const needsSearchIndex = action === 'search' || action === 'detail' || action === 'timeline';
-      const context = readOnlyActions.has(action)
+      const longTermReadOnly = longTermAction === 'list' || longTermAction === 'show';
+      const context = readOnlyActions.has(action) || longTermReadOnly
         ? await getCliReadContext({ searchIndex: needsSearchIndex })
         : await getCliProjectContext({ searchIndex: true });
       const { project, dataDir, reader, identity } = context;
@@ -425,6 +438,178 @@ export default defineCommand({
           return;
         }
 
+        case 'long-term': {
+          const resolvedLongTermAction = longTermAction ?? 'list';
+          const longTermPositional = positional.slice(1);
+          const {
+            archiveLongTermMemory,
+            approveLongTermMemory,
+            createManualLongTermMemory,
+            getLongTermMemoryDetail,
+            listLongTermMemories,
+            promoteObservationToLongTermMemory,
+            qualifyLongTermMemory,
+            supersedeLongTermMemory,
+          } = await import('../../memory/long-term.js');
+          const { resolveLocalMemoryOwner } = await import('../../memory/owner.js');
+          const owner = await resolveLocalMemoryOwner(dataDir, { create: false });
+          const longTermReader = {
+            projectId: project.id,
+            ...(owner ? { ownerId: owner.id } : {}),
+            ...(reader.agentId ? { agentId: reader.agentId } : {}),
+            ...(reader.isTeamMember ? { isTeamMember: true } : {}),
+          };
+
+          const memoryId = (): string => {
+            const id = (args.id as string | undefined)?.trim()
+              || (args.fromObservation as string | undefined)?.trim()
+              || longTermPositional[0]?.trim();
+            if (!id) throw new Error('long-term memory id is required.');
+            return id;
+          };
+          const scope = () => longTermScope(args.scope as string | undefined);
+          const kind = () => longTermKind(args.kind as string | undefined);
+          const portability = () => longTermPortability(args.portability as string | undefined);
+          const reason = () => requiredLongTermReason(args.reason as string | undefined);
+
+          switch (resolvedLongTermAction) {
+            case 'list': {
+              const memories = await listLongTermMemories({
+                dataDir,
+                reader: longTermReader,
+                includeInactive: !!args.all,
+                limit: parsePositiveInt(args.limit as string | undefined, 50),
+              });
+              emitResult(
+                { project, memories },
+                memories.length === 0
+                  ? 'No long-term memories are visible in the active scope.'
+                  : memories.map(item => `- ${item.memory.id} [${item.memory.state}/${item.memory.kind}/${item.memory.scope}] ${item.memory.title}`).join('\n'),
+                asJson,
+              );
+              return;
+            }
+
+            case 'show': {
+              const detail = await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              emitResult(
+                { project, ...detail },
+                [
+                  `${detail.memory.id} [${detail.memory.state}/${detail.memory.kind}/${detail.memory.scope}]`,
+                  detail.memory.title,
+                  detail.memory.content,
+                  `Evidence: ${detail.evidence.length}`,
+                  `Audit events: ${detail.events.length}`,
+                ].join('\n'),
+                asJson,
+              );
+              return;
+            }
+
+            case 'add': {
+              const content = getStringArg(args.text as string | undefined, longTermPositional);
+              if (!content) {
+                emitError('text is required for "memorix memory long-term add"', asJson);
+                return;
+              }
+              const result = await createManualLongTermMemory({
+                dataDir,
+                projectId: project.id,
+                scope: scope(),
+                kind: kind(),
+                title: (args.title as string | undefined)?.trim() || content.slice(0, 100),
+                content,
+                facts: parseCsvList(args.facts as string | undefined),
+                tags: parseCsvList(args.tags as string | undefined),
+                applicability: (args.applicability as string | undefined)?.trim(),
+                portability: portability(),
+                reader: longTermReader,
+              });
+              emitResult(
+                { project, ...result },
+                `Created long-term memory candidate ${result.memory.id}. Qualify it after checking its evidence.`,
+                asJson,
+              );
+              return;
+            }
+
+            case 'promote': {
+              const rawId = (args.fromObservation as string | undefined)?.trim()
+                || (args.id as string | undefined)?.trim()
+                || longTermPositional[0]?.trim();
+              const observationId = Number.parseInt(rawId || '', 10);
+              if (!Number.isFinite(observationId)) {
+                emitError('fromObservation or id must be an observation ID for "memorix memory long-term promote"', asJson);
+                return;
+              }
+              const observation = getObservation(observationId, project.id);
+              if (!observation || !canManageObservation(observation, reader)) {
+                emitError('Observation was not found or is outside the active write scope.', asJson);
+                return;
+              }
+              const result = await promoteObservationToLongTermMemory({
+                dataDir,
+                observation,
+                scope: scope(),
+                kind: kind(),
+                tags: parseCsvList(args.tags as string | undefined),
+                applicability: (args.applicability as string | undefined)?.trim(),
+                reader: longTermReader,
+              });
+              emitResult(
+                { project, sourceObservationId: observation.id, ...result },
+                `Promoted observation #${observation.id} to long-term memory candidate ${result.memory.id}.`,
+                asJson,
+              );
+              return;
+            }
+
+            case 'qualify': {
+              await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              const memory = await qualifyLongTermMemory({ dataDir, id: memoryId(), reason: reason() });
+              emitResult({ project, memory }, `Qualified long-term memory ${memory.id}.`, asJson);
+              return;
+            }
+
+            case 'approve': {
+              await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              const memory = await approveLongTermMemory({ dataDir, id: memoryId(), reason: reason() });
+              emitResult({ project, memory }, `Approved long-term memory ${memory.id}.`, asJson);
+              return;
+            }
+
+            case 'archive': {
+              await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              const memory = await archiveLongTermMemory({ dataDir, id: memoryId(), reason: reason() });
+              emitResult({ project, memory }, `Archived long-term memory ${memory.id}.`, asJson);
+              return;
+            }
+
+            case 'supersede': {
+              const supersededBy = (args.supersededBy as string | undefined)?.trim()
+                || (args['superseded-by'] as string | undefined)?.trim();
+              if (!supersededBy) {
+                emitError('supersededBy is required for "memorix memory long-term supersede"', asJson);
+                return;
+              }
+              await getLongTermMemoryDetail({ dataDir, id: memoryId(), reader: longTermReader });
+              await getLongTermMemoryDetail({ dataDir, id: supersededBy, reader: longTermReader });
+              const memory = await supersedeLongTermMemory({
+                dataDir,
+                id: memoryId(),
+                supersededBy,
+                reason: reason(),
+              });
+              emitResult({ project, memory }, `Superseded long-term memory ${memory.id} with ${supersededBy}.`, asJson);
+              return;
+            }
+
+            default:
+              emitError('long-term action must be list, show, add, promote, qualify, approve, archive, or supersede.', asJson);
+          }
+          return;
+        }
+
         default:
           console.log('Memorix Memory Commands');
           console.log('');
@@ -440,6 +625,13 @@ export default defineCommand({
           console.log('  memorix memory deduplicate [--query "..."] [--dryRun]');
           console.log('  memorix memory consolidate [--action preview|execute] [--threshold 0.45]');
           console.log('  memorix memory promote --ids 42,43 [--trigger "..."] [--instruction "..."]');
+          console.log('  memorix memory long-term list [--all]');
+          console.log('  memorix memory long-term add --kind semantic --scope user --portability portable --title "..." --text "..." [--tags "..."] [--applicability "..."]');
+          console.log('  memorix memory long-term promote --fromObservation 42 --kind procedural --scope project');
+          console.log('  memorix memory long-term qualify --id <id> --reason "verified against evidence"');
+          console.log('  memorix memory long-term approve --id <id> --reason "reviewed by operator"');
+          console.log('  memorix memory long-term archive --id <id> --reason "no longer current"');
+          console.log('  memorix memory long-term supersede --id <old-id> --superseded-by <qualified-id> --reason "replaced"');
       }
     } catch (error) {
       emitError(error instanceof Error ? error.message : String(error), asJson);
@@ -459,3 +651,27 @@ function getIdArg(args: Record<string, unknown>, positional: string[]): string {
     positional.join(',')
   );
 }
+
+function longTermKind(value: string | undefined): 'episodic' | 'semantic' | 'procedural' {
+  const normalized = (value ?? 'semantic').trim().toLowerCase();
+  if (normalized === 'episodic' || normalized === 'semantic' || normalized === 'procedural') return normalized;
+  throw new Error('long-term kind must be episodic, semantic, or procedural.');
+}
+
+function longTermScope(value: string | undefined): 'project' | 'user' | 'team' {
+  const normalized = (value ?? 'project').trim().toLowerCase();
+  if (normalized === 'project' || normalized === 'user' || normalized === 'team') return normalized;
+  throw new Error('long-term scope must be project, user, or team.');
+}
+
+function longTermPortability(value: string | undefined): 'project-bound' | 'portable' {
+  const normalized = (value ?? 'project-bound').trim().toLowerCase();
+  if (normalized === 'project-bound' || normalized === 'portable') return normalized;
+  throw new Error('long-term portability must be project-bound or portable.');
+}
+
+function requiredLongTermReason(value: string | undefined): string {
+  const reason = value?.trim();
+  if (!reason) throw new Error('reason is required for this long-term memory transition.');
+  return reason;
+}