memorix 1.1.13 → 1.2.0

package/docs/dev-log/progress.txt

@@ -4,43 +4,123 @@
 > older notes when they conflict.
 
 ## Current State
-- Phase: 1.1.13 ready to publish
-- Branch: `codex/1.1.13-release-contract`
-- Last updated: 2026-07-17
-- Goal: make Codex global setup diagnosable end to end, remove the accidental
-  workspace publish lane, restore the Star History chart, then publish a clean
-  1.1.13 before beginning 1.2 work.
-
-## Completed Recently
-- Released `memorix@1.1.12`, tagged `v1.1.12`, with native Codex lifecycle
-  hooks, Windows-safe OpenCode hook resolution, scope-isolated setup, and
-  cache-first semantic-vector hydration.
-- `memorix setup --agent codex --global` now stamps the copied plugin manifest
-  with the running Memorix version instead of leaving the template version.
-- `memorix doctor agents --agent codex --scope global` now reports four
-  independently useful facts: the local bundle and declared hook contract, the
-  Personal marketplace entry, Codex's installed/enabled plugin state, and the
-  trusted state for each Codex lifecycle hook.
-- Repair only refreshes Memorix-owned files. A disabled plugin or untrusted
-  hook remains an explicit user action in Codex's plugin/hook UI.
-- `@memorix/ai`, `@memorix/agent-core`, `@memorix/tui`, and
-  `@memorix/memcode` are explicitly internal workspaces. The public release
-  contract is the bundled root `memorix` package.
-- Restored the AVIDS2/memorix Star History chart at the bottom of both READMEs.
-
-## Verification Snapshot
-- Focused Codex setup, hook, doctor, and release-contract regressions pass.
-- `npm run lint`, `npm run build`, and the full serial `npm test` suite pass.
-- `npm pack --dry-run` includes the root runtime, plugin templates, hooks,
-  READMEs, and docs at `memorix@1.1.13`.
-- A clean normal npm installation of the tarball completed a real stdio MCP
-  store/search call against an isolated Git repository and exposed the expected
-  seven-tool micro profile.
-- An isolated real Codex CLI setup installed and enabled `memorix@personal`,
-  stamped the manifest at `1.1.13`, and let doctor verify the bundle,
-  marketplace, runtime state, and pending first-use hook trust separately.
-- The Star History embed uses Star History's current `/image` README endpoint.
-
-## Next Steps
-- Push/merge/tag/publish `v1.1.13`, then create the 1.2 development baseline
-  from the released main branch.
+- Phase: 1.2 release validation and publication
+- Branch: `codex/1.2.0-multidimensional-memory`
+- Last updated: 2026-07-18
+- Released baseline: `memorix@1.1.13`, tag `v1.1.13`, PR #129 merged as
+  `7e8077f`.
+- Goal: turn Memorix from a useful narrative-memory layer into a task-ready
+  working-context layer where code state, change evidence, verification,
+  source-backed project knowledge, workflows, and durable decisions are ranked
+  together.
+
+## 1.1.13 Closeout
+- Codex setup now stamps plugin versions and doctor distinguishes bundle,
+  marketplace, installed/enabled state, declared hooks, and hook trust.
+- Root package publishing is isolated from internal `@memorix/*` workspaces.
+- Full tests, build, pack inspection, isolated MCP smoke, isolated Codex smoke,
+  and Ubuntu/Windows CI all passed before release.
+
+## 1.2 Accepted Direction
+- The [1.2 Product Story](../1.2.0-PRODUCT-STORY.md) is the canonical
+  user-facing narrative; the Development Charter is its implementation
+  contract.
+- The [Knowledge and Workflow Research](../1.2.0-KNOWLEDGE-WORKFLOW-RESEARCH.md)
+  establishes Knowledge Workspace and Workflow Inheritance as 1.2 core product
+  layers, with an explicit boundary against claiming the existing memory map is
+  already a semantic graph or maintained LLM Wiki.
+- The [1.2 Implementation Plan](../1.2.0-IMPLEMENTATION-PLAN.md) is the
+  execution contract for the single complete 1.2 goal. All phases are internal
+  gates in one continuous delivery path, not separate user approval points.
+- Use the [1.2 Development Charter](../1.2.0-DEVELOPMENT-CHARTER.md) as the
+  working product contract.
+- Keep the current SQLite CodeGraph tables and incremental refresh as the base;
+  do not discard working 1.1 Code Memory.
+- Add versioned Code State and evidence-quality semantics before new parsers,
+  external providers, or user-visible tool surfaces.
+- Treat natural-language `memorix_project_context` as the product surface;
+  internal graph/provider complexity must stay behind it.
+
+## Phase 0 Evaluation Foundation
+- Existing UI/API projections now identify themselves honestly as a read-only
+  Memory Overview and deterministic Memory Map. They are not presented as a
+  maintained wiki or semantic graph.
+- The Workset evaluation harness has fixture repositories for TypeScript,
+  Python, Go, docs-only, dirty worktree, deleted-symbol, and incomplete-scan
+  cases. Its seed manifest covers observations, Git facts, test evidence,
+  mini-skills, and explicit graph relations.
+- The harness compares memory-only, current-context, and candidate Worksets
+  against source/evidence/caution requirements and variant token ceilings.
+- The current Auto Context path is smoke-tested against real local TypeScript
+  and dirty-worktree fixtures with embeddings disabled. The candidate budget is
+  180 tokens; the current baseline budget is 320 tokens.
+- The former memory map remains separate from the formal Claim Ledger. Phase 2
+  owns claim provenance, conflict, and supersession semantics; Phase 0 only
+  prevents the old views from being mislabeled as those capabilities.
+
+## Phase 1 Code State
+- Lite refresh now appends a Code State Snapshot with bounded Git revision and
+  worktree metadata, a source epoch, a prior-snapshot link, and explicit scan
+  completeness.
+- Current files, symbols, edges, and current observation-code refs are marked
+  with the latest completed snapshot. Existing CodeGraph rows survive the
+  additive schema migration.
+- Project Context, the CodeGraph MCP status payload, and the codegraph CLI
+  status output expose the latest snapshot. A non-Git directory reports
+  unavailable instead of clean.
+
+## Phase 2 Claim Ledger
+- SQLite now has additive, transactional tables for claims, evidence
+  references, and lifecycle events. Every stored claim requires at least one
+  source reference and credential values are sanitized before durable writes.
+- Exact normalized assertions reuse their record and attach more evidence;
+  competing approved assertions remain disputed rather than being overwritten.
+  Evidence-aware supersession preserves an audit trail.
+- Explicit memories and Git-ingested facts can derive conservative claims.
+  Hook/model output does not become approved knowledge automatically.
+- Observation code references inherit the latest Code State Snapshot when they
+  are created. CodeGraph refresh requalifies bound claims: changed or deleted
+  symbols become unknown, and incomplete scans force review instead of false
+  certainty.
+- Unit and integration tests cover evidence validation, redaction, conflict,
+  supersession, model-review policy, snapshot binding, changed-symbol
+  requalification, and compact task selection.
+
+## Phase 3 Knowledge Workspace
+- Memorix now initializes a private local Markdown workspace by default. A
+  versioned workspace requires an explicit absolute path inside the Git project
+  and refuses ignored or unsafe target directories.
+- Approved active claims compile into Markdown proposals with frontmatter,
+  source claim ids, evidence references, snapshot context, a catalog, and an
+  append-only change log. Proposed pages are not silently published.
+- The knowledge init, status, compile, apply, and lint commands provide the
+  operator path. Applying a proposal protects a manual page edit by default;
+  an explicit force flag is the only overwrite path and is logged.
+- Workspace lint detects malformed frontmatter, broken links, orphan pages,
+  missing claims/evidence, superseded claims, unresolved conflicts, stale code
+  snapshots, and protected manual edits.
+- The compiled CLI was smoke-tested in an isolated Git project through init,
+  compile, apply, and lint with a source-backed claim.
+
+## 1.2 Delivery Complete, Release Checks In Progress
+- Phase 4 added canonical Markdown workflows, safe adapter preview/apply, import,
+  selection, and verification receipts. Agent instruction files are render
+  targets, not the workflow source of truth.
+- Phase 5 routes Project Context and Context Pack through one bounded Workset
+  assembler. It ranks current facts, claims, knowledge pages, workflows, and
+  cautions instead of dumping unrelated narrative memory.
+- Phase 6 makes refresh, claim derivation/requalification, knowledge
+  compile/lint, workflow indexing, retention, and consolidation durable
+  maintenance work. Interactive MCP requests do not scan an entire corpus.
+- Phase 7 adds an optional local semantic CodeGraph boundary. Lite remains the
+  durable local fallback; external output is used only from a healthy existing
+  `.codegraph` index, is validated, bounded, and never persisted as raw code.
+- The advanced `memorix_knowledge` MCP action tool now exposes explicit
+  workspace/proposal/workflow management only in `team` and `full` profiles.
+- Completed local release gates: lint, full test suite, production build,
+  package-content audit, isolated Windows npm install, stdio MCP smoke, and
+  HTTP dashboard/lifecycle smoke.
+- Release audit also incorporated #130 before publication: the optional SQLite
+  runtime now uses the Node-26-compatible `better-sqlite3` 12.x line, with a
+  dedicated Node 26 CI smoke that opens an in-memory database.
+- Remaining remote gates: GitHub CI, npm publish, tag, and GitHub release.

package/llms-full.txt

@@ -2,10 +2,23 @@
 
 > Local-first shared memory layer for AI coding agents.
 
-Memorix is a TypeScript/Node.js project that gives AI coding agents persistent, project-aware memory. It targets software development workflows, not generic chat. It works across Claude Code, Codex, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, Pi, Kiro, Antigravity, Trae, and any agent that can speak MCP over stdio or HTTP. Integrations usually start with `memorix setup --agent <agent> --global`, which installs the recommended user-level package or config for that agent: plugin packages when supported, package or extension entries, MCP config, generated guidance, hooks, skills, or the bundled terminal agent.
+Memorix is a TypeScript/Node.js project that gives AI coding agents persistent, project-aware memory. It targets software development workflows, not generic chat. It works across Claude Code, Codex, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, and any agent that can speak MCP over stdio or HTTP. Integrations usually start with `memorix setup --agent <agent> --global`, which installs the recommended user-level package or config for that agent: plugin packages when supported, package or extension entries, MCP config, generated guidance, hooks, skills, or the bundled terminal agent.
 
 If you are an AI coding agent helping a user install, operate, or troubleshoot Memorix, read `docs/AGENT_OPERATOR_PLAYBOOK.md` before taking action. It is the main reference for install, runtime selection, Git/project binding, MCP integration, hooks, and troubleshooting.
 
+## 1.2 Multi-Dimensional Memory Model
+
+Memorix is not a transcript dump. The normal agent path is `memorix_project_context` or `memorix context --task "..."`, which assembles a bounded task Workset: current Git/package facts, selected observations and reasoning, Code State freshness, source-backed claims, matching knowledge/workflow starts, cautions, and verification hints.
+
+- **Observation, Reasoning, and Git Memory** preserve durable engineering facts.
+- **Code State** records versioned local file, symbol, import, and memory-to-code links so prior evidence can be requalified when code moves.
+- **Claim Ledger** keeps provenance, confidence, conflicts, and lifecycle state separate from prose.
+- **Knowledge Workspace** compiles claims into reviewable Markdown proposals; it does not silently overwrite manually edited pages.
+- **Canonical Workflows** represent project process once and render conservative agent-specific adapters only on explicit request.
+- **Lifecycle maintenance** uses durable, resumable jobs so indexing, claim requalification, knowledge compile/lint, retention, and consolidation do not turn an interactive MCP request into a corpus-sized foreground job.
+
+The built-in CodeGraph Lite provider is a structural local fallback, not a complete semantic graph. If a project already has a healthy local CodeGraph index, `[codegraph].external_context = "auto"` can add a small validated semantic outline. Memorix never runs `codegraph init`, `index`, or `sync`, does not transmit the repository, and does not persist raw external code output.
+
 ## Entry Points
 
 ### Setup package
@@ -348,7 +361,7 @@ Docker is for the HTTP service. The container must have access to the repositori
 
 ## Supported Clients
 
-Memorix supports Claude Code, Codex, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, Pi, Kiro, Antigravity, Trae, memcode, and other stdio or HTTP MCP clients.
+Memorix supports Claude Code, Codex, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, memcode, and other stdio or HTTP MCP clients.
 
 Support depth differs by client:
 
@@ -356,6 +369,7 @@ Support depth differs by client:
 - MCP is the common integration layer.
 - Claude Code, Codex, and GitHub Copilot CLI receive local plugin packages.
 - Pi receives a user-level package when setup runs with `--global`; Gemini CLI receives a local extension package.
+- OpenClaw receives a compatible bundle; Hermes Agent receives a plugin package; Oh-my-Pi receives a package/extension entry.
 - Project instructions and rules include AGENTS.md, GEMINI.md, Cursor rules, Windsurf rules, Kiro steering, and Trae rules.
 - Hooks are generated for agents that expose usable hook events.
 - OpenCode receives a local plugin file at `.opencode/plugins/memorix.js`, an OpenCode skill at `.opencode/skills/memorix-memory/SKILL.md`, plus `opencode.json` MCP config.

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Local-first shared memory layer for AI coding agents.
 
-Memorix gives coding agents persistent, project-aware memory across sessions, IDEs, terminals, and MCP clients. It stores project knowledge once so multiple agents can retrieve it — through plugin packages, MCP, CLI, SDK, generated rules/instructions, hooks, skills, local plugins, or the bundled terminal agent. It works with Claude Code, Codex, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, Pi, Kiro, Antigravity, Trae, and other MCP-capable agents.
+Memorix gives coding agents persistent, project-aware memory across sessions, IDEs, terminals, and MCP clients. It stores project knowledge once so multiple agents can retrieve it through plugin packages, MCP, CLI, SDK, generated rules/instructions, hooks, skills, local plugins, or the bundled terminal agent. It works with Claude Code, Codex, Cursor, Windsurf, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, Trae, and other MCP-capable agents.
 
 ## Entry Points
 
@@ -10,20 +10,25 @@ Memorix gives coding agents persistent, project-aware memory across sessions, ID
 - `memorix setup --list` lists supported agent entry points.
 - `memorix serve` starts the manual stdio MCP server for IDEs and agents.
 - `memorix background start` starts the HTTP MCP service and dashboard.
-- `memorix memory`, `reasoning`, `session`, `team`, `task`, `handoff`, `poll`, `receipt`, `sync`, `ingest`, and `orchestrate` expose the CLI command set.
+- `memorix memory`, `codegraph`, `knowledge`, `reasoning`, `session`, `team`, `task`, `handoff`, `poll`, `receipt`, `sync`, `ingest`, and `orchestrate` expose the CLI command set.
 - `memorix integrate --agent <agent>` and `memorix hooks install --agent <agent>` are manual/fallback generation commands.
 - `memorix` and `memcode` open memcode, the bundled terminal agent that uses the same project memory pool.
 - `memorix dashboard` opens the local read-mostly dashboard.
 
 ## Memory Model
 
-Memorix combines three layers:
+Memorix combines durable memory with a bounded task Workset:
 
 - **Observation Memory**: facts, gotchas, fixes, implementation notes, what changed
 - **Reasoning Memory**: why decisions were made, alternatives, constraints, risks
 - **Git Memory**: commit-derived engineering facts with source provenance
+- **Code State**: versioned local file/symbol/import facts and freshness links that keep memory tied to the current checkout
+- **Claim Ledger and Knowledge Workspace**: source-backed claims compiled into reviewable Markdown proposals, never silent overwrites
+- **Canonical Workflows**: project workflows with safe per-agent adapters and recorded verification outcomes
 
-Search is project-scoped by default. Use global scope only when cross-project recall is intentional.
+For non-trivial coding work, agents normally call `memorix_project_context` (or `memorix context --task "...")`. It selects a small task Workset with current facts, relevant evidence, start files, cautions, and verification hints instead of dumping all old text memory. Search is project-scoped by default. Use global scope only when cross-project recall is intentional.
+
+The built-in CodeGraph Lite index is structural and intentionally not presented as a complete semantic graph. A project that already has a healthy local CodeGraph index can contribute a small validated semantic outline through `[codegraph].external_context = "auto"`; Memorix never initializes, syncs, exports, or remotely uploads that index.
 
 ## memcode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.1.13",
+  "version": "1.2.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,
@@ -61,6 +61,7 @@
     "test:watch": "vitest",
     "test:llm-live": "MEMORIX_RUN_LIVE_LLM_TESTS=1 vitest run tests/integration/formation-llm-quality.test.ts",
     "test:e2e": "vitest run tests/e2e/",
+    "benchmark:codegraph": "node scripts/benchmark-codegraph-provider.cjs",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build && npm test"
   },
@@ -137,7 +138,7 @@
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^3.0.0",
-    "better-sqlite3": "^11.0.0"
+    "better-sqlite3": "^12.11.1"
   },
   "overrides": {
     "tar": "^7.5.16",

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

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

package/src/cli/capability-map.ts

@@ -6,6 +6,7 @@ export const CLI_NATIVE_PARITY: Record<string, string> = Object.freeze({
   memorix_project_context: 'memorix context',
   memorix_context_pack: 'memorix codegraph context-pack',
   memorix_codegraph_status: 'memorix codegraph status',
+  memorix_knowledge: 'memorix knowledge init|status|compile|lint|apply|workflow',
   memorix_resolve: 'memorix memory resolve',
   memorix_timeline: 'memorix memory timeline',
   memorix_suggest_topic_key: 'memorix memory suggest-topic-key',

package/src/cli/commands/codegraph.ts

@@ -1,20 +1,54 @@
 import { defineCommand } from 'citty';
 import { CodeGraphStore } from '../../codegraph/store.js';
 import { refreshProjectLite } from '../../codegraph/lite-provider.js';
-import { assembleContextPackForTask, buildContextPackPrompt } from '../../codegraph/context-pack.js';
+import { assembleContextPackForTask, attachTaskWorkset, buildContextPackPrompt } from '../../codegraph/context-pack.js';
 import { backfillMissingObservationCodeRefs } from '../../codegraph/binder.js';
+import { collectCurrentProjectFacts } from '../../codegraph/current-facts.js';
+import { resolveTaskLens } from '../../codegraph/task-lens.js';
+import { getExternalCodeGraphContext, inspectExternalCodeGraph } from '../../codegraph/external-provider.js';
+import type { CodeGraphProviderQuality } from '../../codegraph/types.js';
 import { getResolvedConfig } from '../../config/resolved-config.js';
 import { getAllObservations } from '../../memory/observations.js';
 import { emitError, emitResult, getCliProjectContext, parsePositiveInt } from './operator-shared.js';
 
-function formatStatus(status: ReturnType<CodeGraphStore['status']>): string {
+function formatSnapshotStatus(status: ReturnType<CodeGraphStore['status']>): string[] {
+  const snapshot = status.latestSnapshot;
+  if (!snapshot) return ['- Code state: no completed snapshot yet'];
+  const revision = snapshot.baseRevision ? snapshot.baseRevision.slice(0, 12) : 'Git unavailable';
+  const completeness = snapshot.completeness;
+  const scanState = completeness.skippedOversizedFiles > 0
+    || (completeness.unreadableFiles ?? 0) > 0
+    || completeness.removalScanDeferred
+    ? 'incomplete'
+    : 'complete';
   return [
+    '- Code state: ' + revision
+      + ', ' + snapshot.worktreeState + ' worktree'
+      + ', ' + snapshot.changedPathCount + ' changed path(s)'
+      + ', epoch ' + snapshot.sourceEpoch,
+    '- Scan completeness: ' + scanState
+      + ' (' + completeness.scannedFiles + '/' + completeness.maxFiles + ' paths'
+      + ', ' + completeness.skippedOversizedFiles + ' oversized skipped'
+      + ', ' + (completeness.unreadableFiles ?? 0) + ' unreadable)',
+  ];
+}
+
+function formatStatus(status: ReturnType<CodeGraphStore['status']>, quality?: CodeGraphProviderQuality): string {
+  return [
+    ...formatSnapshotStatus(status),
     `CodeGraph Memory: ${status.provider}`,
     `- Files: ${status.files}`,
     `- Symbols: ${status.symbols}`,
     `- Edges: ${status.edges}`,
     `- Memory refs: ${status.refs}`,
     status.indexedAt ? `- Indexed at: ${status.indexedAt}` : '- Indexed at: never',
+    ...(quality
+      ? [
+        `- Persistent provider: ${status.provider} (heuristic local index)`,
+        `- External semantic CodeGraph: ${quality.external.state}`
+          + (quality.external.reason ? ` (${quality.external.reason})` : ''),
+      ]
+      : []),
   ].join('\n');
 }
 
@@ -29,6 +63,19 @@ function formatUsageHint(): string {
   ].join('\n');
 }
 
+function compactFacts(project: { rootPath: string }): { facts: string[]; dirty: boolean } {
+  const current = collectCurrentProjectFacts({ project, now: new Date() });
+  const facts: string[] = [];
+  if (current.packageVersion) facts.push('Package version: ' + current.packageVersion);
+  if (current.latestChangelog) {
+    facts.push('Latest changelog: ' + current.latestChangelog.version
+      + (current.latestChangelog.date ? ' (' + current.latestChangelog.date + ')' : ''));
+  }
+  facts.push('Git: ' + (current.git.branch ? 'branch ' + current.git.branch + ', ' : '')
+    + (current.git.dirty ? 'dirty worktree' : 'clean worktree'));
+  return { facts, dirty: current.git.dirty };
+}
+
 export default defineCommand({
   meta: {
     name: 'codegraph',
@@ -56,10 +103,16 @@ export default defineCommand({
       switch (action) {
         case 'status': {
           const status = store.status(project.id);
+          const providerQuality = await inspectExternalCodeGraph({
+            projectRoot: project.rootPath,
+            mode: codegraphConfig.externalContext,
+            command: codegraphConfig.externalCommand,
+            timeoutMs: codegraphConfig.externalTimeoutMs,
+          });
           const text = explicitAction || asJson
-            ? formatStatus(status)
-            : `${formatStatus(status)}\n\n${formatUsageHint()}`;
-          emitResult({ project, status }, text, asJson);
+            ? formatStatus(status, providerQuality.quality)
+            : `${formatStatus(status, providerQuality.quality)}\n\n${formatUsageHint()}`;
+          emitResult({ project, status, providerQuality: providerQuality.quality }, text, asJson);
           return;
         }
 
@@ -73,12 +126,25 @@ export default defineCommand({
           const activeObservations = getAllObservations()
             .filter(obs => obs.projectId === project.id && (obs.status ?? 'active') === 'active');
           const backfill = await backfillMissingObservationCodeRefs(store, activeObservations);
+          const { enqueueClaimRequalification } = await import('../../runtime/lifecycle.js');
+          enqueueClaimRequalification({
+            dataDir,
+            projectId: project.id,
+            source: 'manual-codegraph-refresh',
+            snapshotId: refresh.snapshot.id,
+          });
           const status = store.status(project.id);
+          const providerQuality = await inspectExternalCodeGraph({
+            projectRoot: project.rootPath,
+            mode: codegraphConfig.externalContext,
+            command: codegraphConfig.externalCommand,
+            timeoutMs: codegraphConfig.externalTimeoutMs,
+          });
           emitResult(
-            { project, status, refresh, backfill },
+            { project, status, providerQuality: providerQuality.quality, refresh, backfill },
             [
               'CodeGraph Memory refreshed.',
-              formatStatus(status),
+              formatStatus(status, providerQuality.quality),
               `- Files: ${refresh.changedFiles} changed, ${refresh.unchangedFiles} unchanged, ${refresh.removedFiles} removed`,
               `- Backfilled memories: ${backfill.observationsBackfilled}`,
               `- Backfilled refs: ${backfill.refsBackfilled}`,
@@ -98,7 +164,7 @@ export default defineCommand({
           const observations = getAllObservations()
             .filter(obs => obs.projectId === project.id && (obs.status ?? 'active') === 'active')
             .reverse();
-          const pack = assembleContextPackForTask({
+          const basePack = assembleContextPackForTask({
             store,
             projectId: project.id,
             task,
@@ -106,7 +172,44 @@ export default defineCommand({
             limit,
             exclude,
           });
-          emitResult({ project, pack }, buildContextPackPrompt(pack), asJson);
+          const status = store.status(project.id);
+          const facts = compactFacts(project);
+          const snapshot = status.latestSnapshot;
+          const external = await getExternalCodeGraphContext({
+            projectRoot: project.rootPath,
+            task,
+            exclude,
+            mode: codegraphConfig.externalContext,
+            command: codegraphConfig.externalCommand,
+            timeoutMs: codegraphConfig.externalTimeoutMs,
+          });
+          const pack = await attachTaskWorkset({
+            pack: basePack,
+            projectId: project.id,
+            dataDir,
+            lens: resolveTaskLens(task).id,
+            worktreeDirty: facts.dirty,
+            currentFacts: facts.facts,
+            codeState: formatSnapshotStatus(status).join(' '),
+            ...(snapshot
+              ? {
+                snapshot: {
+                  id: snapshot.id,
+                  sourceEpoch: snapshot.sourceEpoch,
+                  worktreeState: snapshot.worktreeState,
+                  incomplete: snapshot.completeness.skippedOversizedFiles > 0
+                    || (snapshot.completeness.unreadableFiles ?? 0) > 0
+                    || snapshot.completeness.removalScanDeferred,
+                },
+              }
+              : {}),
+            ...(external.outline ? { semanticCode: external.outline } : {}),
+            providerQuality: external.quality,
+            ...(external.caution
+              ? { runtimeCautions: [{ kind: 'external-codegraph-fallback' as const, message: external.caution }] }
+              : {}),
+          });
+          emitResult({ project, pack, providerQuality: external.quality }, buildContextPackPrompt(pack), asJson);
           return;
         }
 

package/src/cli/commands/context.ts

@@ -45,6 +45,8 @@ export default defineCommand({
           currentFacts: context.currentFacts,
           overview: context.overview,
           refresh: context.refresh,
+          providerQuality: context.providerQuality,
+          workset: context.workset,
           ...(context.task ? { task: context.task } : {}),
         },
         formatAutoProjectContextPrompt(context),

package/src/cli/commands/doctor.ts

@@ -319,9 +319,11 @@ export default defineCommand({
         const { CodeGraphStore } = await import('../../codegraph/store.js');
         const { buildProjectContextOverview } = await import('../../codegraph/project-context.js');
         const { getResolvedConfig } = await import('../../config/resolved-config.js');
+        const { inspectExternalCodeGraph } = await import('../../codegraph/external-provider.js');
         const codeStore = new CodeGraphStore();
         await codeStore.init(dataDir);
-        const exclude = getResolvedConfig({ projectRoot: projectRoot || process.cwd() }).codegraph.excludePatterns;
+        const codegraphConfig = getResolvedConfig({ projectRoot: projectRoot || process.cwd() }).codegraph;
+        const exclude = codegraphConfig.excludePatterns;
         const overview = buildProjectContextOverview({
           project: {
             id: projectId,
@@ -335,6 +337,12 @@ export default defineCommand({
         const languageText = overview.code.languages.length > 0
           ? overview.code.languages.map((item: any) => `${item.language} ${item.files}`).join(', ')
           : 'none indexed yet';
+        const providerQuality = await inspectExternalCodeGraph({
+          projectRoot: projectRoot || process.cwd(),
+          mode: codegraphConfig.externalContext,
+          command: codegraphConfig.externalCommand,
+          timeoutMs: codegraphConfig.externalTimeoutMs,
+        });
 
         if (overview.code.files > 0) {
           lines.push(ok(`Code memory: ${overview.code.files} files, ${overview.code.symbols} symbols, ${overview.code.refs} memory links`));
@@ -344,6 +352,15 @@ export default defineCommand({
           tips.push('Run `memorix codegraph refresh` once to seed project context.');
         }
 
+        lines.push(info(
+          `Code provider: Lite durable index; external semantic graph ${providerQuality.health.state}`,
+        ));
+        if (providerQuality.health.state !== 'ready'
+          && providerQuality.health.state !== 'not-detected'
+          && providerQuality.health.state !== 'disabled') {
+          lines.push(warn(`External CodeGraph: ${providerQuality.health.reason ?? providerQuality.health.state}`));
+        }
+
         if (overview.freshness.stale > 0 || overview.freshness.suspect > 0) {
           lines.push(warn(`Freshness: ${overview.freshness.current} current, ${overview.freshness.suspect} suspect, ${overview.freshness.stale} stale`));
         } else {
@@ -362,6 +379,7 @@ export default defineCommand({
           refs: overview.code.refs,
           languages: overview.code.languages,
           freshness: overview.freshness,
+          providerQuality: providerQuality.quality,
           ...(overview.code.indexedAt ? { indexedAt: overview.code.indexedAt } : {}),
         };
       } catch (e) {
@@ -373,7 +391,58 @@ export default defineCommand({
       lines.push(info('Project context unavailable without a detected project.'));
     }
 
-    // ── 6. Conflict Check ────────────────────────────────────────
+    // ── 6. Knowledge Lifecycle ──────────────────────────────────
+    lines.push('');
+    lines.push('┌─ Knowledge Lifecycle ─────────────────────────────');
+
+    if (projectId && dataDir) {
+      try {
+        const { collectLifecycleDiagnostics } = await import('../../runtime/lifecycle-status.js');
+        const lifecycle = await collectLifecycleDiagnostics({ dataDir, projectId });
+        report.lifecycle = lifecycle;
+
+        const queued = lifecycle.maintenance.summary.pending + lifecycle.maintenance.summary.retrying;
+        const running = lifecycle.maintenance.summary.running;
+        if (lifecycle.maintenance.summary.failed > 0) {
+          lines.push(warn(`Maintenance: ${lifecycle.maintenance.summary.failed} failed job(s)`));
+          for (const job of lifecycle.maintenance.failedJobs) {
+            lines.push(info(`Failed: ${job.kind} after ${job.attempts} attempt(s)`));
+          }
+          issues.push('Knowledge maintenance has failed work. Run `memorix doctor --json` to inspect the affected job kind.');
+        } else if (queued > 0 || running > 0) {
+          lines.push(info(`Maintenance: ${queued} queued, ${running} running`));
+        } else {
+          lines.push(ok('Maintenance: idle'));
+        }
+
+        lines.push(info(
+          `Claims: ${lifecycle.claims.active} active, ${lifecycle.claims.needsReview} need review, ${lifecycle.claims.unknown} unknown`,
+        ));
+        if (lifecycle.claims.conflicts > 0) {
+          lines.push(warn(`Claim conflicts: ${lifecycle.claims.conflicts}`));
+          issues.push('Source-backed claims conflict and need review before they guide work.');
+        }
+
+        if (lifecycle.workspaces.length === 0) {
+          lines.push(info('Knowledge workspace: not initialized'));
+        } else {
+          for (const workspace of lifecycle.workspaces) {
+            lines.push(info(
+              `${workspace.mode} workspace: ${workspace.pages} pages, ${workspace.pendingProposals} pending proposal(s), ${workspace.status}`,
+            ));
+          }
+        }
+        lines.push(info(`Workflows: ${lifecycle.workflows.active}/${lifecycle.workflows.total} active, ${lifecycle.workflows.failedRuns} failed run(s)`));
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        lines.push(warn(`Knowledge lifecycle unavailable: ${message}`));
+        report.lifecycle = { error: message };
+      }
+    } else {
+      lines.push(info('Knowledge lifecycle unavailable without a detected project.'));
+    }
+
+    // ── 7. Conflict Check ────────────────────────────────────────
     lines.push('');
     lines.push('┌─ Conflict Check ──────────────────────────────────');
 
@@ -403,7 +472,7 @@ export default defineCommand({
     }
     report.conflicts = { found: conflictsFound };
 
-    // ── 7. LLM Status ────────────────────────────────────────────
+    // ── 8. LLM Status ────────────────────────────────────────────
     lines.push('');
     lines.push('┌─ LLM Enhanced Mode ───────────────────────────────');
 
@@ -427,7 +496,7 @@ export default defineCommand({
       report.llm = { enabled: false };
     }
 
-    // ── 8. Auto-Update Status ──────────────────────────────────
+    // ── 9. Auto-Update Status ──────────────────────────────────
     lines.push('');
     lines.push('┌─ Auto-Update ─────────────────────────────────────');