memorix 1.2.0 → 1.2.2

package/docs/DEVELOPMENT.md

@@ -271,6 +271,10 @@ to make sure provenance diagnostics match runtime behavior.
 
 ## 9. Release Workflow
 
+The repository's canonical workflow is [Memorix release](knowledge/workflows/memorix-release.md).
+It is the versioned source for agents and maintainers; its checks supplement,
+rather than replace, the explicit maintainer approval required to publish.
+
 Recommended release flow:
 
 1. update docs and version metadata

package/docs/README.md

@@ -87,7 +87,7 @@ The public docs are organized by user intent:
 | 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) |
+| Active context-control work | [1.2.2 Memory Control Plane](1.2.2-MEMORY-CONTROL-PLANE.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) |
 

package/docs/SETUP.md

@@ -276,12 +276,18 @@ Manual stdio shape:
   "mcpServers": {
     "memorix": {
       "command": "memorix",
-      "args": ["serve"]
+      "args": ["serve"],
+      "alwaysLoad": true
     }
   }
 }
 ```
 
+Keep `alwaysLoad: true` for a manually managed Claude Code entry so its small
+Memorix tool set is available during print-mode startup. `memorix doctor agents
+--agent claude` reports a missing eager-load setting, and `memorix repair agents
+--agent claude` restores it without replacing unrelated MCP servers.
+
 ### Cursor
 
 Project config: `.cursor/mcp.json`

package/docs/dev-log/progress.txt

@@ -4,15 +4,15 @@
 > older notes when they conflict.
 
 ## Current State
-- 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.
+- Phase: 1.2.2 memory-control-plane admission and visibility implementation
+- Branch: `codex/1.2.2-memory-control-plane`
+- Last updated: 2026-07-25
+- Released baseline: `memorix@1.2.1`, tag `v1.2.1`, `origin/main` at
+  `1b5bf7f`.
+- Goal: make the 1.2 multi-dimensional evidence layer behave as one bounded,
+  explainable control plane. A task Workset, hook handoff, lifecycle refresh,
+  and provider capability result must share evidence qualification, delivery
+  budgets, and privacy-safe receipts.
 
 ## 1.1.13 Closeout
 - Codex setup now stamps plugin versions and doctor distinguishes bundle,
@@ -102,7 +102,7 @@
 - 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
+## 1.2 Delivery Complete, Released As 1.2.1
 - 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.
@@ -123,4 +123,84 @@
 - 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.
+- The release was completed as `memorix@1.2.1`. Its next development line is
+  [1.2.2 Memory Control Plane](../1.2.2-MEMORY-CONTROL-PLANE.md), which
+  consolidates these capabilities instead of adding another disconnected
+  memory feature.
+
+## 1.2.2 Control Plane
+- `TaskWorkset` already has bounded rendering and source-aware claims, but
+  SessionStart handoff and legacy context surfaces need one shared admission,
+  budget, and receipt contract.
+- First implementation slice complete: the shared `ContextReceipt` records
+  delivery target, selected source ids/kinds, trust/freshness, exact budget
+  omissions, queued refreshes, and Workset selection time without entering the
+  agent prompt. Project Context, Context Pack, and full SessionStart injection
+  now carry the same delivery-target semantics; `memorix explain` exposes the
+  receipt in text and JSON.
+- Budget selection now keeps a knowledge page dependent on a Claim out of the
+  prompt when its qualifying Claim could not fit. The receipt records both as
+  withheld instead of presenting an orphaned page path as usable knowledge.
+- Phase 3 admission slice complete: automatic observations now persist an
+  `ephemeral`, `candidate`, or `qualified` state and a reason. Hooks and the
+  internal orchestrator capture concrete evidence as candidates, keep routine
+  success/telemetry ephemeral, and drop low-signal activity without writing it.
+  Automatic capture stays quiet in the host agent.
+- A deduplicated `observation-qualify` maintenance job runs after CodeGraph
+  refresh. It requires a scan no older than the capture and at least one
+  current code reference before upgrading a candidate. Qualification does not
+  create a Claim; explicit saves and Git remain the Claim boundary.
+- Auto Project Context, automatic session L1 delivery, Wiki/Knowledge Graph
+  compilation, and graph-context packets exclude candidates and ephemeral
+  traces. Ordinary search prefers qualified material, while explicit lookup
+  can still inspect pending evidence.
+- Pending automatic evidence is also excluded from automatic consolidation so
+  a later qualification can still inspect its original source grain. Retention
+  explanations no longer describe an unqualified `core` candidate as immune.
+- Actor and visibility enforcement is now one policy shared by MCP retrieval,
+  auto context, CLI/TUI, dashboards, knowledge/graph projections, and scoped
+  maintenance. Legacy observations remain project-visible; new records may be
+  `project`, `team`, or `personal` with an explicit creator and recipients.
+  Missing identity never grants private or team visibility.
+- Automatic hooks and orchestrator traces begin personal. A verified hook
+  candidate may become project evidence only when qualification proves a
+  current code reference. Targeted handoffs are readable by sender and
+  recipient but writable only by sender; broadcasts require an active project
+  team member.
+- Automatic orchestration lesson lookup is explicitly project-scoped, so its
+  prompt injection cannot read personal or team-scoped records.
+- Topic-key writes now check mutation scope before storage, and the
+  project-attribution guard receives only memories visible to its current
+  reader. This closes both guessed-key overwrite and cross-project existence
+  hints without hiding historical project knowledge after upgrade.
+- The embedded SDK remains project-visible when unbound. CLI and the local TUI
+  now share the same explicit actor reader: an unbound terminal sees project
+  memory only, while `memorix identity join|use` (or one-shot `--as`) grants
+  only that active project member's personal/team visibility and coordination
+  ergonomics. `identity clear` returns to project scope; private evidence
+  cannot be promoted into shared skills or generated project skills.
+- CLI control-plane ergonomics now include `--cwd`, kebab-case flag aliases,
+  action-oriented namespace help, explicit `memorix workbench`, and
+  file/stdin transfer import/export. Root memory aliases use the same
+  canonical command paths as `memorix memory`; CLI and MCP exports are filtered
+  by the same active reader so an unbound backup cannot contain private/team
+  observations.
+- Direct CLI and foreground Code Memory refreshes now enqueue qualification as
+  well as claim requalification, and they register the local project target
+  needed by the isolated control-plane worker. The host hook path persists its
+  candidate before scheduling a refresh, avoiding a fast-worker race where a
+  scan could predate the capture.
+- Compiled-artifact smoke: an isolated Codex `PostToolUse` hook returned only
+  `continue: true`, stored a `candidate`, and the isolated background control
+  plane upgraded it to `qualified` after a real Code Memory scan with one
+  current reference. Embeddings were deliberately disabled for this
+  deterministic local smoke. The full test suite, TypeScript check, and
+  production build also passed after the admission policy was reconciled with
+  OpenCode's concise technical response events.
+- #135 remains a contributor-owned session-handoff candidate for the bounded
+  `HandoffPacket` phase. It is not copied or silently replaced.
+- #133/#134 remain open pending an official provider-capability layer and a
+  safe agent-facing media path. The existing OpenRouter text embedding path is
+  the supported baseline.
+- See [1.2.2 Memory Control Plane](../1.2.2-MEMORY-CONTROL-PLANE.md) for
+  phases, acceptance gates, non-goals, and release criteria.

package/docs/knowledge/workflows/memorix-release.md

@@ -0,0 +1,57 @@
+---
+id: memorix-release
+title: Memorix release
+description: Prepare a Memorix release with evidence, package verification, and explicit maintainer approval.
+status: active
+version: 1
+taskLenses: [release]
+triggers: [release, publish, npm, version, changelog]
+allowedAgents: [codex, claude-code, cursor, windsurf, copilot, antigravity, gemini-cli, openclaw, hermes, omp, kiro, opencode, trae]
+verificationGates:
+  - Version and changelog match the release scope
+  - npm run lint passes
+  - npm run build passes
+  - npm test passes
+  - Focused live MCP smoke passes when server behavior changed
+  - Package smoke passes
+  - CI passes on the release commit
+  - Maintainer approval is explicit before publishing
+---
+
+## Inspect
+
+Read the current version, changelog, Git state, open release risks, and the
+diff that will ship. Do not treat a release tag, an old test run, or a local
+token as proof that this exact commit is ready.
+
+## Prepare
+
+Update version metadata, changelog, and user-facing documentation only for
+changes that are actually included. Keep package workspace visibility and npm
+access settings unchanged unless the release specifically changes them.
+
+## Verify
+
+Run `npm run lint`, `npm run build`, and `npm test`. Run focused tests for the
+changed surface. When MCP behavior changed, use a real isolated stdio client to
+exercise the affected tool path. Inspect `npm pack --dry-run --json` and run a
+package smoke from the packed artifact when packaging changed.
+
+## Review
+
+Record what passed, what was not run, and any remaining risk. Confirm that the
+release commit has passing CI. A workflow may prepare evidence, but publishing
+requires explicit maintainer approval.
+
+## Publish
+
+After explicit maintainer approval, publish through the approved release path.
+Never put credentials in the repository, release notes, workflow files, or
+command output. Verify the published package version without exposing tokens.
+
+## Follow Up
+
+Check a fresh install or `npx` invocation, create or update the GitHub release
+if appropriate, and reply to affected issue reporters with the concrete fix and
+version. Store the verification evidence as project knowledge rather than an
+unstructured chat note.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,

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

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

package/src/audit/index.ts

@@ -1,156 +1,156 @@
-/**
- * Audit Module - Track Memorix-written files
- *
- * Records all files written by Memorix to distinguish them from
- * project-native files. Provides audit trail for cleanup and rollback.
- */
-
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { homedir } from 'node:os';
-
-function getAuditFilePath(): string {
-  return process.env.MEMORIX_AUDIT_FILE || path.join(homedir(), '.memorix', 'audit.json');
-}
-
-export interface AuditEntry {
-  type: 'hook' | 'rule' | 'other';
-  agent?: string;
-  path: string;
-  createdAt: string;
-}
-
-export interface ProjectAudit {
-  projectRoot: string;
-  installedAt: string;
-  entries: AuditEntry[];
-}
-
-export interface AuditData {
-  version: string;
-  projects: Record<string, ProjectAudit>;
-}
-
-/**
- * Load audit data from disk.
- */
-export async function loadAudit(): Promise<AuditData> {
-  try {
-    const content = await fs.readFile(getAuditFilePath(), 'utf-8');
-    return JSON.parse(content) as AuditData;
-  } catch {
-    // No audit file yet
-    return {
-      version: '1.0.0',
-      projects: {},
-    };
-  }
-}
-
-/**
- * Save audit data to disk.
- */
-export async function saveAudit(data: AuditData): Promise<void> {
-  const auditFile = getAuditFilePath();
-  const dir = path.dirname(auditFile);
-  await fs.mkdir(dir, { recursive: true });
-  await fs.writeFile(auditFile, JSON.stringify(data, null, 2), 'utf-8');
-}
-
-/**
- * Get project ID from project root via .git detection.
- */
-export function getProjectId(projectRoot: string): string {
-  try {
-    const { detectProject } = require('../project/detector.js');
-    const project = detectProject(projectRoot);
-    if (project) return project.id;
-  } catch { /* fallback below */ }
-  const normalized = projectRoot.replace(/\\/g, '/');
-  return `untracked/${normalized}`;
-}
-
-/**
- * Record a file written by Memorix.
- */
-export async function recordFile(
-  projectRoot: string,
-  type: AuditEntry['type'],
-  filePath: string,
-  agent?: string,
-): Promise<void> {
-  const data = await loadAudit();
-  const projectId = getProjectId(projectRoot);
-
-  if (!data.projects[projectId]) {
-    data.projects[projectId] = {
-      projectRoot,
-      installedAt: new Date().toISOString(),
-      entries: [],
-    };
-  }
-
-  // Check if entry already exists
-  const existingIndex = data.projects[projectId].entries.findIndex(
-    (e) => e.path === filePath
-  );
-
-  if (existingIndex === -1) {
-    data.projects[projectId].entries.push({
-      type,
-      agent,
-      path: filePath,
-      createdAt: new Date().toISOString(),
-    });
-  }
-
-  await saveAudit(data);
-}
-
-/**
- * Get all files written by Memorix for a project.
- */
-export async function getProjectFiles(projectRoot: string): Promise<AuditEntry[]> {
-  const data = await loadAudit();
-  const projectId = getProjectId(projectRoot);
-  return data.projects[projectId]?.entries || [];
-}
-
-/**
- * Remove a file from audit (when uninstalled).
- */
-export async function removeFile(projectRoot: string, filePath: string): Promise<void> {
-  const data = await loadAudit();
-  const projectId = getProjectId(projectRoot);
-
-  if (!data.projects[projectId]) return;
-
-  data.projects[projectId].entries = data.projects[projectId].entries.filter(
-    (e) => e.path !== filePath
-  );
-
-  // If no entries left, remove the project
-  if (data.projects[projectId].entries.length === 0) {
-    delete data.projects[projectId];
-  }
-
-  await saveAudit(data);
-}
-
-/**
- * Get all audit entries across all projects.
- */
-export async function getAllAuditEntries(): Promise<
-  Array<{ projectId: string; entry: AuditEntry }>
-> {
-  const data = await loadAudit();
-  const entries: Array<{ projectId: string; entry: AuditEntry }> = [];
-
-  for (const [projectId, project] of Object.entries(data.projects)) {
-    for (const entry of project.entries) {
-      entries.push({ projectId, entry });
-    }
-  }
-
-  return entries;
-}
+/**
+ * Audit Module - Track Memorix-written files
+ *
+ * Records all files written by Memorix to distinguish them from
+ * project-native files. Provides audit trail for cleanup and rollback.
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { homedir } from 'node:os';
+
+function getAuditFilePath(): string {
+  return process.env.MEMORIX_AUDIT_FILE || path.join(homedir(), '.memorix', 'audit.json');
+}
+
+export interface AuditEntry {
+  type: 'hook' | 'rule' | 'other';
+  agent?: string;
+  path: string;
+  createdAt: string;
+}
+
+export interface ProjectAudit {
+  projectRoot: string;
+  installedAt: string;
+  entries: AuditEntry[];
+}
+
+export interface AuditData {
+  version: string;
+  projects: Record<string, ProjectAudit>;
+}
+
+/**
+ * Load audit data from disk.
+ */
+export async function loadAudit(): Promise<AuditData> {
+  try {
+    const content = await fs.readFile(getAuditFilePath(), 'utf-8');
+    return JSON.parse(content) as AuditData;
+  } catch {
+    // No audit file yet
+    return {
+      version: '1.0.0',
+      projects: {},
+    };
+  }
+}
+
+/**
+ * Save audit data to disk.
+ */
+export async function saveAudit(data: AuditData): Promise<void> {
+  const auditFile = getAuditFilePath();
+  const dir = path.dirname(auditFile);
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(auditFile, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+/**
+ * Get project ID from project root via .git detection.
+ */
+export function getProjectId(projectRoot: string): string {
+  try {
+    const { detectProject } = require('../project/detector.js');
+    const project = detectProject(projectRoot);
+    if (project) return project.id;
+  } catch { /* fallback below */ }
+  const normalized = projectRoot.replace(/\\/g, '/');
+  return `untracked/${normalized}`;
+}
+
+/**
+ * Record a file written by Memorix.
+ */
+export async function recordFile(
+  projectRoot: string,
+  type: AuditEntry['type'],
+  filePath: string,
+  agent?: string,
+): Promise<void> {
+  const data = await loadAudit();
+  const projectId = getProjectId(projectRoot);
+
+  if (!data.projects[projectId]) {
+    data.projects[projectId] = {
+      projectRoot,
+      installedAt: new Date().toISOString(),
+      entries: [],
+    };
+  }
+
+  // Check if entry already exists
+  const existingIndex = data.projects[projectId].entries.findIndex(
+    (e) => e.path === filePath
+  );
+
+  if (existingIndex === -1) {
+    data.projects[projectId].entries.push({
+      type,
+      agent,
+      path: filePath,
+      createdAt: new Date().toISOString(),
+    });
+  }
+
+  await saveAudit(data);
+}
+
+/**
+ * Get all files written by Memorix for a project.
+ */
+export async function getProjectFiles(projectRoot: string): Promise<AuditEntry[]> {
+  const data = await loadAudit();
+  const projectId = getProjectId(projectRoot);
+  return data.projects[projectId]?.entries || [];
+}
+
+/**
+ * Remove a file from audit (when uninstalled).
+ */
+export async function removeFile(projectRoot: string, filePath: string): Promise<void> {
+  const data = await loadAudit();
+  const projectId = getProjectId(projectRoot);
+
+  if (!data.projects[projectId]) return;
+
+  data.projects[projectId].entries = data.projects[projectId].entries.filter(
+    (e) => e.path !== filePath
+  );
+
+  // If no entries left, remove the project
+  if (data.projects[projectId].entries.length === 0) {
+    delete data.projects[projectId];
+  }
+
+  await saveAudit(data);
+}
+
+/**
+ * Get all audit entries across all projects.
+ */
+export async function getAllAuditEntries(): Promise<
+  Array<{ projectId: string; entry: AuditEntry }>
+> {
+  const data = await loadAudit();
+  const entries: Array<{ projectId: string; entry: AuditEntry }> = [];
+
+  for (const [projectId, project] of Object.entries(data.projects)) {
+    for (const entry of project.entries) {
+      entries.push({ projectId, entry });
+    }
+  }
+
+  return entries;
+}