memorix 1.1.13 → 1.2.0

package/docs/1.2.0-PROVIDER-QUALITY.md

@@ -0,0 +1,189 @@
+# Memorix 1.2 Code Provider Quality
+
+Memorix needs useful code evidence without pretending that every local index is
+a full semantic graph. This document defines the quality contract for Code
+Memory providers and the optional integration with a locally indexed CodeGraph
+CLI.
+
+## The User-Facing Rule
+
+Project Context may say one of three truthful things:
+
+1. **Lite structural evidence**: Memorix found files, declarations, and import
+   hints with its built-in offline index. It is useful for starting points, but
+   it is heuristic rather than a language-server-quality graph.
+2. **External semantic evidence**: a locally indexed CodeGraph installation
+   returned validated symbols and relationships for this task. Memorix may use
+   those results as an extra, bounded outline.
+3. **External graph unavailable or stale**: Memorix falls back to Lite and
+   tells the agent why it did not use the external graph. It never labels the
+   fallback as complete semantic coverage.
+
+An agent does not need to remember a different command for these cases. The
+normal path remains `memorix_project_context` or `memorix context --task ...`.
+The diagnostics path shows which evidence quality was actually used.
+
+## Built-In Lite: Useful, but Bounded
+
+Lite is bundled with Memorix and needs no parser download, service, or network
+connection. It incrementally records supported source files, declaration-like
+symbols, import hints, file hashes, and versioned Code State snapshots.
+
+It currently recognizes source-file extensions for TypeScript/JavaScript,
+Python, Go, Rust, Java, C#, C/C++, PHP, Ruby, and Kotlin. Its declaration and
+import recognition uses conservative language profiles, not a compiler or AST.
+Therefore Lite must not claim any of the following:
+
+- complete symbol extraction;
+- resolved imports or cross-file call targets;
+- type-aware references, routes, tests, inheritance, or data flow;
+- immunity to comments, strings, unusual syntax, generated code, or parser
+  ambiguity.
+
+Lite is still the durable fallback. It owns local snapshots and code-reference
+freshness, so an external provider is never required to recover existing
+Memorix memory.
+
+## Optional External CodeGraph
+
+When a repository already has a healthy, local CodeGraph index, Memorix can ask
+its CLI for a small task-specific semantic outline. This is an enhancement, not
+a replacement database and not an automatic installation.
+
+Memorix only considers the external provider when all of these are true:
+
+1. external context is enabled by the project configuration;
+2. the project already contains CodeGraph's `.codegraph` marker;
+3. `codegraph status --json` reports an initialized index for the exact project
+   root;
+4. the index has no reported pending changes or worktree mismatch;
+5. the bounded command completes before its configured timeout; and
+6. the returned JSON passes Memorix's schema, path, count, and output-size
+   validation.
+
+Memorix never runs `codegraph init`, `index`, or `sync` on the user's behalf.
+It does not transmit the repository to a remote service. Its default request is
+equivalent to:
+
+~~~powershell
+codegraph context --path <project-root> --format json --max-nodes 8 --no-code <task>
+~~~
+
+`--no-code` is intentional. Memorix consumes a small outline of paths,
+symbols, locations, and relationships; it does not copy raw code blocks into
+the Workset or its own database. The CodeGraph command itself remains under the
+user's local installation and project boundary.
+
+## Configuration
+
+The default is `auto`: a pre-existing local `.codegraph` index is treated as an
+explicit project-level opt-in, but Memorix will not create or refresh it. Set
+the mode to `off` to use Lite only.
+
+~~~toml
+[codegraph]
+# "auto" (default) uses a healthy, pre-indexed local CodeGraph when present.
+# "off" always uses the built-in Lite provider.
+external_context = "auto"
+
+# Optional only when CodeGraph is not available on PATH.
+# external_command = "C:\\tools\\codegraph.cmd"
+
+# A bounded local query. Values outside the safe range are clamped.
+external_timeout_ms = 1200
+~~~
+
+The equivalent YAML keys are `externalContext`, `externalCommand`, and
+`externalTimeoutMs`. Configuration contains a command path and timeout only;
+it must never hold an API key or provider credential.
+
+## Provider Contract
+
+Both providers report a machine-readable quality object with:
+
+| Field | Meaning |
+| --- | --- |
+| selected provider | Lite or external semantic provider actually used for this brief |
+| mode | configured external policy (`auto` or `off`) |
+| state | ready, disabled, unavailable, stale, timed out, invalid, or fallback |
+| capabilities | declared symbols, imports, resolved relations, locations, and coverage level |
+| coverage | provider-reported indexed file/language counts and Lite scan limits when known |
+| reason | a short sanitized explanation for a downgrade |
+
+The status is visible through `memorix codegraph status --json`, `memorix
+doctor --json`, and Project Context JSON. Prompt output keeps it compact: it
+adds semantic start points only when a valid external outline is available, and
+adds one caution when a requested external outline was not safe to use.
+
+## Validation and Fallback
+
+The external adapter executes without a shell, pins the working directory to
+the actual project root, uses a bounded timeout and stdout limit, and accepts
+JSON only. It rejects a result when:
+
+- the status belongs to another project root;
+- the index is uninitialized, has pending changes, or reports a worktree
+  mismatch;
+- required output fields have the wrong type;
+- a returned path is absolute, escapes the project root, or is excluded;
+- returned node, edge, or related-file counts exceed Memorix's caps; or
+- the command times out, exits unsuccessfully, or emits oversized output.
+
+Rejected data is never persisted as Lite facts, claims, or wiki evidence. The
+agent receives Lite context plus a short caution. This protects the durable
+memory layer from a stale or malformed external tool while preserving a useful
+offline response.
+
+## Reproducible Quality Gate
+
+The provider suite uses deterministic fixture repositories and a fake command
+runner. It verifies:
+
+1. Lite capability and scan-limit reporting remains honest.
+2. A valid external outline adds only bounded semantic start points and
+   relationship facts.
+3. Stale, mismatched, malformed, timed-out, and oversized external output
+   safely falls back to Lite.
+4. Raw code blocks and credentials do not enter the default Workset.
+5. `codegraph status` and `doctor` identify the active/fallback provider.
+
+The optional real smoke can be run on a Windows project that already has an
+indexed CodeGraph installation:
+
+~~~powershell
+memorix codegraph status --json
+memorix context --task "trace the authentication request"
+~~~
+
+For a comparable Lite refresh and task-context measurement, build Memorix and
+run the checked-in harness. It does not create or sync an external CodeGraph
+index; point it at a project that has already opted in and been indexed.
+
+~~~powershell
+npm run build
+npm run benchmark:codegraph -- --path C:\\work\\my-project --task "trace the authentication request"
+~~~
+
+The JSON result records Lite refresh time/counts, selected task provider,
+external health, semantic entry-point/relation counts, and prompt tokens. It
+contains no raw source code.
+
+### Windows Smoke Record
+
+The following is a real 2026-07-18 Windows smoke against a two-file TypeScript
+fixture using the locally installed CodeGraph CLI. It is a small reproducible
+sanity check, not a general performance claim:
+
+| Measurement | Result |
+| --- | --- |
+| `codegraph status --json` cold process | 609 ms |
+| `codegraph context --format json --max-nodes 8 --no-code` | 376 ms |
+| semantic result | 2 symbols, 1 resolved `calls` relation |
+| Memorix task Workset | external semantic provider, 1 relation, 100 tokens |
+
+The built-in Lite provider intentionally reports no resolved relation
+capability. This is why the optional provider is treated as an enhancement,
+not silently presented as equivalent evidence.
+
+The result is successful only when it reports exactly what was used. A missing
+or stale external index is a supported state, not a hidden failure.

package/docs/1.2.0-WORKFLOW-INHERITANCE.md

@@ -0,0 +1,101 @@
+# Memorix 1.2 Workflow Inheritance
+
+Workflow inheritance gives a project a portable, reviewable description of how
+it is normally changed. It is deliberately separate from a chat summary and
+from any one agent's configuration format.
+
+## What a workflow is
+
+A canonical workflow is a Markdown file in the Knowledge Workspace
+\`workflows/\` directory. Its frontmatter describes:
+
+- a stable id, title, description, version, and lifecycle state;
+- task lenses and trigger phrases used for selection;
+- assumptions, required context, guardrails, and allowed tools;
+- ordered phases, branches, expected outputs, and verification gates;
+- source claim, evidence, and code references; and
+- the agent formats it may be rendered to.
+
+The body contains the concise project-specific instructions. A workflow is not
+a replacement for agent judgment: it makes the project's recurring quality
+checks and delivery shape discoverable at the moment they are useful.
+
+## Ownership and safety
+
+The canonical Markdown file is the source of truth. Agent-specific files are
+adapters, not peer sources.
+
+- Existing \`.windsurf/workflows/*.md\` files can be imported read-only. Import
+  never alters the source file.
+- Memorix-generated adapters contain an ownership marker. Apply may replace
+  only a file carrying that exact marker.
+- A user-created file at an adapter target is preserved. The operation reports
+  a conflict instead of overwriting it.
+- Adapter writes stay project-scoped. They never edit global settings,
+  \`CLAUDE.md\`, MCP configuration, or an agent's unrelated rules.
+- Preview is the default. Apply is explicit and uses atomic writes.
+
+The result is compatible with agents that support project skills or rules,
+while keeping the workflow understandable without any particular agent
+installed.
+
+## Selection and progressive delivery
+
+Memorix uses the current task wording and a compact task lens to choose no
+more than two active workflows. It selects only an explicit match; a generic
+task receives no workflow rather than boilerplate.
+
+The normal Project Context result contains the workflow title, why it matched,
+its first phase, and its verification gates. It does not inject the complete
+workflow body into every prompt. A caller can request the full workflow when
+that work actually begins.
+
+## Workflow runs
+
+Each run records the task, selected workflow, starting code snapshot, phase
+state, selected evidence, outcome, verification verdict, and failure reason.
+Runs are operational metadata in SQLite; canonical Markdown remains the
+reviewable project artifact.
+
+A failed verification gate is carried into later Worksets as a visible caution.
+Repeated failure may create an improvement proposal. Memorix never changes a
+workflow source file merely because an agent failed a run.
+
+## Example
+
+\`\`\`markdown
+---
+id: release-checklist
+title: Release checklist
+description: Prepare a patch release without losing release evidence.
+status: active
+version: 1
+taskLenses: [release]
+triggers: [release, publish, npm]
+allowedAgents: [codex, claude-code, cursor, windsurf]
+verificationGates: [tests pass, package smoke passes, changelog reviewed]
+---
+
+## Prepare
+
+1. Read current package metadata, changelog, and unresolved release blockers.
+2. Run the focused verification before changing release files.
+
+## Publish
+
+Only publish after package smoke and changelog review pass.
+\`\`\`
+
+## Operator commands
+
+\`\`\`text
+memorix knowledge workflow import
+memorix knowledge workflow list
+memorix knowledge workflow select --task "prepare the patch release"
+memorix knowledge workflow preview --id release-checklist --agent codex
+memorix knowledge workflow apply --id release-checklist --agent codex
+memorix knowledge workflow run --id release-checklist --task "publish 1.2.0" --outcome passed
+\`\`\`
+
+The workflow namespace is an advanced operator surface. Normal agents use the
+existing Project Context path and should not need to memorize these commands.

package/docs/1.2.0-WORKSET-RETRIEVAL.md

@@ -0,0 +1,80 @@
+# Memorix 1.2 Task Workset Retrieval
+
+A Task Workset is the compact answer Memorix prepares for one concrete task.
+It is the product surface of the 1.2 data model: code state, source-qualified
+claims, reviewed knowledge pages, workflow starts, and verification evidence
+become useful only when they are selected together and kept small.
+
+## Normal agent experience
+
+The normal entry point remains:
+
+    memorix_project_context({ task: "..." })
+
+No new MCP tool is required. The same task can be passed to the CLI:
+
+    memorix context --task "..."
+
+Memorix returns an action-oriented brief:
+
+1. start files or symbols;
+2. only task-matching claims with stable claim and evidence references;
+3. at most two matching workflow starts, not full playbook text;
+4. visible cautions for dirty code, incomplete scans, stale memory, disputed
+   claims, and failed workflow verification; and
+5. a short verification plan.
+
+When no current claim, page, or workflow is relevant, Memorix returns less
+context. It does not insert a generic knowledge dump merely because a project
+has a database.
+
+## Selection policy
+
+The Workset starts with the existing task lens and source ranking, then applies
+these bounded additions:
+
+| Source | Inclusion rule | Default cap |
+| --- | --- | --- |
+| Start points | Existing lens-ranked current paths | 5 |
+| Claims | Approved, task-matching active/disputed/unknown assertions | 3 |
+| Knowledge pages | Published pages linked to selected claims | 2 |
+| Workflows | Explicit task-lens or trigger match | 2 |
+| Verification | Workflow gates, evidence-backed test hints, then lens hints | 4 |
+| Cautions | Current safety state; never silently dropped | 6 |
+
+The default rendered brief has a 180-token target. Whole items are dropped
+before any source text is cut. The JSON form retains stable ids, source
+references, selection reasons, and truncation information for diagnostics.
+
+## Evidence and freshness
+
+A claim in the Workset carries its claim id and evidence refs; it is not
+formatted as unqualified project truth. A published knowledge page is a
+navigation pointer, not its entire Markdown body.
+
+Code state has precedence:
+
+- a dirty worktree becomes a Workset caution;
+- an incomplete latest scan becomes a Workset caution;
+- suspect or stale code-memory bindings become cautions;
+- disputed or review-needed claims remain visible as cautions rather than
+  being silently ranked above current code;
+- a previously failed selected workflow verification is shown before that
+  workflow is reused.
+
+## Performance and failure boundary
+
+Workset assembly reads existing local SQLite metadata and known workflow/page
+records. It does not scan the repository, compile pages, read full wiki bodies,
+call an LLM, or invoke an external graph service in the foreground request.
+
+If a knowledge artifact is missing or unavailable, the code-state brief still
+works. A missing optional layer removes only that layer; it does not make
+Project Context fail or substitute unqualified text.
+
+## Compatibility
+
+The existing context pack remains available and compatible. It keeps its
+current source/memory shape while sharing Workset provenance in its structured
+form. The default MCP profile stays small: Project Context is still the
+single recommended first call.

package/docs/AGENT_OPERATOR_PLAYBOOK.md

@@ -25,9 +25,9 @@ It supports:
 - local-first project-scoped memory
 - cross-agent recall across Cursor, Claude Code, Codex, Windsurf, Gemini CLI, GitHub Copilot, OpenCode, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Kiro, Antigravity, and Trae
 
-### Current 1.1 Baseline
+### Current 1.2 Baseline
 
-For the 1.1 release line, the visible product shape is:
+For the 1.2 release line, the visible product shape is:
 
 - `memorix setup --agent <agent> --global` is the default integration command for an existing coding agent or IDE
 - setup installs plugin packages where supported, MCP config, usage guidance, hooks, and skills according to agent capability
@@ -38,6 +38,9 @@ For the 1.1 release line, the visible product shape is:
 - model lanes are separate: `[memory.llm]` for formation/rerank/summaries, `[embedding]` for semantic search, `[agent]` for the model memcode talks to while coding
 - legacy `memorix.yml`, `.env`, and `~/.memorix/config.json` are compatibility inputs, not the recommended setup path
 - generated agent rules treat `memorix_session_start` as optional unless explicit session semantics matter
+- `memorix_project_context` / `memorix context --task "..."` is the normal black-box entry for non-trivial coding work: it assembles a bounded task Workset instead of injecting a generic memory dump
+- Code State keeps local snapshots and freshness links; a healthy pre-existing local CodeGraph index can add a bounded semantic outline, but Memorix never initializes or synchronizes that external index itself
+- `memorix knowledge` is an explicit review path for source-backed Markdown knowledge and canonical workflows. Do not initialize a versioned workspace or apply a proposal unless the user asks for that managed artifact
 - integration surfaces are agent-specific: Claude Code, Codex, GitHub Copilot CLI, Antigravity, and Hermes receive plugin packages; OpenClaw receives a compatible bundle; Pi and Oh-my-Pi receive package entries; Gemini CLI receives an extension package; OpenCode receives a plugin file and skill; Cursor and other agents receive MCP/rules/hooks where supported
 - privacy-safe diagnostics and receipts avoid raw chat, memory text, query text, tool payloads, and local file paths
 
@@ -47,7 +50,7 @@ For the 1.1 release line, the visible product shape is:
 
 ### CLI is the direct command surface; MCP is the integration layer
 
-For direct use, prefer `memorix ...` commands first. In the 1.1 line, the CLI covers session, memory, reasoning, retention, formation, audit, transfer, skills, orchestration coordination, sync, ingest workflows, and the bundled terminal agent.
+For direct use, prefer `memorix ...` commands first. In the 1.2 line, the CLI covers session, memory, Code State, knowledge workspaces, reasoning, retention, formation, audit, transfer, skills, orchestration coordination, sync, ingest workflows, and the bundled terminal agent.
 
 Do not ask memory-only users to join coordination state. A lightweight session is enough for memory, retrieval, reasoning, and continuation. Use `joinTeam` / `team_manage(join)` only for explicit task/message/lock coordination or for CLI-agent work managed by `memorix orchestrate`.
 

package/docs/API_REFERENCE.md

@@ -37,6 +37,7 @@ The current CLI namespaces are:
 - `memorix session`
 - `memorix memory`
 - `memorix codegraph`
+- `memorix knowledge`
 - `memorix reasoning`
 - `memorix retention`
 - `memorix formation`
@@ -61,6 +62,7 @@ memorix memory search --query "release blocker"
 memorix context --task "continue auth bug"
 memorix codegraph refresh
 memorix codegraph status --json
+memorix knowledge status
 memorix reasoning search --query "why sqlite"
 memorix retention status
 memorix task list
@@ -78,9 +80,9 @@ memorix receipt --json --probe "release blocker"
 
 The CLI is for direct terminal use, not a 1:1 mirror of MCP tool names. The only MCP-only area is the optional graph-compatibility tools (`create_entities`, `read_graph`, and related tools) for workflows that expect the official memory-server style graph API.
 
-### Memory Autopilot, CodeGraph Memory, and Context Packs
+### Memory Autopilot, Code State, and Context Packs
 
-Memory Autopilot is the default agent-facing path for coding context. It uses CodeGraph Memory, project observations, task-lens heuristics, and freshness labels to produce a compact brief instead of dumping raw old chat text. CodeGraph Memory stores structured file, symbol, import-edge, and memory-to-code reference facts in the same local SQLite database as project memory. It is not a replacement for normal file reads. Its job is to help agents decide which memories still point at current code, which ones are stale, and which files/symbols deserve inspection next.
+Memory Autopilot is the default agent-facing path for coding context. It builds a bounded task Workset instead of dumping old chat text: current project facts, Code State, selected observations, source-backed claims, matching knowledge/workflow starts, cautions, and verification hints. Code State stores versioned local file, symbol, import-edge, and memory-to-code reference facts beside project memory. It is not a replacement for normal file reads. Its job is to help agents decide which memories still point at current code, which ones are stale, and which files/symbols deserve inspection next.
 
 CLI:
 
@@ -97,19 +99,36 @@ memorix codegraph context-pack --task "continue auth bug"
 
 MCP:
 
-- `memorix_project_context` builds the default Memory Autopilot brief. It can auto-refresh CodeGraph Memory when the index is missing or stale, infer a task lens (`bugfix`, `feature`, `release`, `onboarding`, `refactor`, `docs`, `test`, or `general`), then return current project facts, Start here files, reliable code-bound memories, stale/suspect cautions, and lens-specific verification hints.
+- `memorix_project_context` builds the default Memory Autopilot brief. It can auto-refresh Code State when the local index is missing or stale, infer a task lens (`bugfix`, `feature`, `release`, `onboarding`, `refactor`, `docs`, `test`, or `general`), then return current project facts, Start here files, selected evidence, stale/suspect cautions, and lens-specific verification hints.
 - `memorix_codegraph_status` returns provider/index counts for the current project.
 - `memorix_context_pack` builds a task-specific packet with reliable current memories, lower-trust unbound memories, current code facts, freshness warnings, suggested reads, and suggested verification.
 
-`memorix context` defaults to `--refresh auto`, so first use can seed CodeGraph Memory without a separate manual `memorix codegraph refresh`. Its brief puts live package/changelog/Git facts before memory hints and flags old `progress.txt` / dev-log notes as historical when they predate the latest changelog, so agents should treat current facts as the source of truth when files disagree. Task lenses keep the packet shaped to the work: bugfix briefs prefer failing tests and repros, release briefs prefer metadata/changelog/package checks, and onboarding briefs prefer docs and entry points while hiding unrelated suspect details. Use `--refresh never` for read-only inspection and `--refresh always` when you want to force a fresh scan.
+`memorix context` defaults to `--refresh auto`, so first use can seed Code State without a separate manual `memorix codegraph refresh`. Its brief puts live package/changelog/Git facts before memory hints and flags old `progress.txt` / dev-log notes as historical when they predate the latest changelog, so agents should treat current facts as the source of truth when files disagree. Task lenses keep the packet shaped to the work: bugfix briefs prefer failing tests and repros, release briefs prefer metadata/changelog/package checks, and onboarding briefs prefer docs and entry points while hiding unrelated suspect details. Use `--refresh never` for read-only inspection and `--refresh always` when you want to force a fresh scan.
 
-Project-specific generated, vendored, or cache paths can be excluded from CodeGraph Memory with `[codegraph].exclude_patterns` in `memorix.toml` or `~/.memorix/config.toml` (`codegraph.excludePatterns` in legacy YAML). User patterns extend the built-in excludes and are applied to indexing, Project Context suggested reads, and Context Pack suggested reads.
+Project-specific generated, vendored, or cache paths can be excluded from Code State with `[codegraph].exclude_patterns` in `memorix.toml` or `~/.memorix/config.toml` (`codegraph.excludePatterns` in legacy YAML). User patterns extend the built-in excludes and are applied to indexing, Project Context suggested reads, and Context Pack suggested reads.
 
 SessionStart hooks keep the default minimal hint lightweight. When memory behavior is configured with `sessionInject=full`, Memorix injects the compact Memory Autopilot brief at session start instead of only listing recent text memories.
 
 The intended loop for agents is: get the project brief when it helps, inspect the suggested current files, use stale or unbound memory only as a lead, store durable outcomes after the work changes the project, and resolve obsolete memories.
 
-The built-in Lite provider indexes common code files with lightweight file, symbol, and import facts. Future providers can feed richer graph data into the same store and context APIs.
+The built-in Lite provider indexes common code files with lightweight file, symbol, and import facts. It is a structural fallback, not a language-server-quality graph. When a project already has a healthy local CodeGraph index, `[codegraph].external_context = "auto"` may add a validated, bounded semantic outline to the Workset. Memorix never initializes, syncs, or exports that external index, and never stores its raw source output. `memorix codegraph status --json`, `memorix doctor --json`, and Project Context JSON identify the actual provider quality.
+
+### Knowledge Workspace and Workflows
+
+`memorix knowledge` is the deliberate, reviewable knowledge-management path. It uses source-backed claims to compile Markdown proposals, protects manually edited pages, and can keep canonical project workflows separate from agent-specific adapters.
+
+```bash
+memorix knowledge init --mode local
+memorix knowledge status
+memorix knowledge compile
+memorix knowledge lint
+memorix knowledge apply --proposal <id>
+memorix knowledge workflow import
+memorix knowledge workflow select --task "prepare a release"
+memorix knowledge workflow preview --id <workflow-id> --agent codex
+```
+
+The advanced MCP action tool is `memorix_knowledge`. It is registered only in the `team` and `full` tool profiles so normal agents keep the compact micro/lite tool surface. Its actions are `workspace_init`, `status`, `compile`, `lint`, `proposal_apply`, `workflow_import`, `workflow_list`, `workflow_select`, `workflow_preview`, `workflow_apply`, and `workflow_run`. Use it only when an agent is explicitly managing the reviewable Knowledge Workspace; ordinary coding work should stay on `memorix_project_context`.
 
 ### Cross-Agent Handoff Receipt
 

package/docs/CONFIGURATION.md

@@ -65,6 +65,11 @@ noise_keywords = ["format", "typo"]
 exclude_patterns = ["vendor/**", "third_party/**", "generated/**"]
 max_file_bytes = 2097152
 
+# Optional: use an already-indexed local CodeGraph only when it is healthy.
+external_context = "auto"
+# external_command = "C:\\tools\\codegraph.cmd"
+external_timeout_ms = 1200
+
 [server]
 transport = "stdio"
 dashboard = true
@@ -209,15 +214,19 @@ the Memorix project ID.
 
 ### `[codegraph]`
 
-CodeGraph Memory and Project Context scan limits.
+Code State, CodeGraph Memory, and Project Context scan/provider settings.
 
 Common keys:
 
 - `exclude_patterns = ["vendor/**", "third_party/**", "generated/**"]`
 - `max_file_bytes = 2097152` (2 MiB per source file by default)
+- `external_context = "auto"` (`"off"` keeps the built-in Lite provider only)
+- `external_command = "C:\\tools\\codegraph.cmd"` (optional path when CodeGraph is not on `PATH`)
+- `external_timeout_ms = 1200` (bounded local semantic-query timeout)
 
-Legacy YAML uses `codegraph.excludePatterns` and `codegraph.maxFileBytes` for
-the same settings.
+Legacy YAML uses `codegraph.excludePatterns`, `codegraph.maxFileBytes`,
+`codegraph.externalContext`, `codegraph.externalCommand`, and
+`codegraph.externalTimeoutMs` for the same settings.
 
 These patterns extend Memorix's built-in CodeGraph excludes (`node_modules`,
 build outputs, worktrees, and similar generated directories). Matching paths are
@@ -226,6 +235,15 @@ suggested reads. Files larger than `max_file_bytes` are also skipped so a
 generated or minified source file cannot monopolize an incremental scan. Raise
 the limit only for a repository where that file is intentional source.
 
+`external_context = "auto"` is deliberately conservative. Memorix checks for
+an already-initialized local `.codegraph` index and uses it only when its status
+matches the current project and has no pending changes. It never runs
+`codegraph init`, `index`, or `sync`, and it never sends repository content to
+a remote service. A valid external response contributes only a small semantic
+outline to the current task Workset; raw code is neither copied into the
+Workset nor persisted as Memorix knowledge. See
+[1.2 Provider Quality](1.2.0-PROVIDER-QUALITY.md) for the complete contract.
+
 ### `[server]`
 
 Server and dashboard behavior.

package/docs/README.md

@@ -31,7 +31,8 @@ The public docs are organized by user intent:
 | Topic | Document |
 | --- | --- |
 | CLI commands and MCP tools | [API_REFERENCE.md](API_REFERENCE.md) |
-| Memory Autopilot, CodeGraph Memory, and context packs | [API_REFERENCE.md § Memory Autopilot, CodeGraph Memory, and Context Packs](API_REFERENCE.md#memory-autopilot-codegraph-memory-and-context-packs), [context fabric design](superpowers/specs/2026-06-29-codegraph-memory-context-fabric-design.md), and [auto context design](superpowers/specs/2026-06-29-auto-context-layer-design.md) |
+| Memory Autopilot, Code State, and context packs | [API_REFERENCE.md § Memory Autopilot, Code State, and Context Packs](API_REFERENCE.md#memory-autopilot-code-state-and-context-packs), [1.2 Code State](1.2.0-CODE-STATE.md), and [1.2 Workset Retrieval](1.2.0-WORKSET-RETRIEVAL.md) |
+| Reviewable knowledge pages and workflow inheritance | [API_REFERENCE.md § Knowledge Workspace and Workflows](API_REFERENCE.md#knowledge-workspace-and-workflows), [1.2 Knowledge Workspace](1.2.0-KNOWLEDGE-WORKSPACE.md), and [1.2 Workflow Inheritance](1.2.0-WORKFLOW-INHERITANCE.md) |
 | Git-derived engineering memory | [GIT_MEMORY.md](GIT_MEMORY.md) |
 | Memory formation and quality pipeline | [MEMORY_FORMATION_PIPELINE.md](MEMORY_FORMATION_PIPELINE.md) |
 | Performance and resource profile | [PERFORMANCE.md](PERFORMANCE.md) |
@@ -75,6 +76,18 @@ The public docs are organized by user intent:
 | Module-by-module notes | [MODULES.md](MODULES.md) |
 | CodeGraph Memory / Context Fabric design | [2026-06-29-codegraph-memory-context-fabric-design.md](superpowers/specs/2026-06-29-codegraph-memory-context-fabric-design.md) |
 | Auto Context Layer design | [2026-06-29-auto-context-layer-design.md](superpowers/specs/2026-06-29-auto-context-layer-design.md) |
+| 1.2 product direction and user journey | [1.2 Product Story](1.2.0-PRODUCT-STORY.md) |
+| 1.2 knowledge base and workflow inheritance research | [Knowledge and Workflow Research](1.2.0-KNOWLEDGE-WORKFLOW-RESEARCH.md) |
+| 1.2 execution contract and phase gates | [1.2 Implementation Plan](1.2.0-IMPLEMENTATION-PLAN.md) |
+| 1.2 deterministic Workset evaluation fixtures | [1.2 Evaluation Harness](1.2.0-EVALUATION-HARNESS.md) |
+| 1.2 versioned code-state contract | [1.2 Code State Snapshots](1.2.0-CODE-STATE.md) |
+| 1.2 source-backed claim and conflict contract | [1.2 Claim Ledger](1.2.0-CLAIM-LEDGER.md) |
+| 1.2 reviewable Markdown knowledge workspace | [1.2 Knowledge Workspace](1.2.0-KNOWLEDGE-WORKSPACE.md) |
+| 1.2 canonical workflows and safe agent adapters | [1.2 Workflow Inheritance](1.2.0-WORKFLOW-INHERITANCE.md) |
+| 1.2 task-shaped evidence selection | [1.2 Workset Retrieval](1.2.0-WORKSET-RETRIEVAL.md) |
+| 1.2 non-blocking refresh and maintenance contract | [1.2 Dynamic Lifecycle](1.2.0-DYNAMIC-LIFECYCLE.md) |
+| 1.2 honest Lite and optional semantic CodeGraph provider contract | [1.2 Provider Quality](1.2.0-PROVIDER-QUALITY.md) |
+| Active 1.2 multi-dimensional memory work | [1.2.0 Development Charter](1.2.0-DEVELOPMENT-CHARTER.md) |
 | Historical cloud sync and multi-agent research | [CLOUD_SYNC_AND_MULTI_AGENT_RESEARCH.md](CLOUD_SYNC_AND_MULTI_AGENT_RESEARCH.md) |
 | Known issues and old roadmap notes | [KNOWN_ISSUES_AND_ROADMAP.md](KNOWN_ISSUES_AND_ROADMAP.md) |
 
@@ -102,7 +115,9 @@ Historical/deep-reference documents may describe older designs. If they conflict
 
 ## Current Product Line
 
-These docs target the **1.1 release line**, where:
+The released product is on the **1.1 line**. Active 1.2 design work is tracked
+in the [1.2 Development Charter](1.2.0-DEVELOPMENT-CHARTER.md). The current
+released baseline has:
 
 - `memorix setup --agent <agent> --global` is the default agent integration command
 - `memorix serve` is the manual stdio MCP server for external agents