memorix 1.2.1 → 1.2.2

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.2.1",
+  "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.1",
+  "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;
+}

package/src/cli/command-guide.ts

@@ -0,0 +1,192 @@
+export interface CliCommandGuide {
+  summary: string;
+  usage: string[];
+  notes?: string[];
+}
+
+const GUIDES: Record<string, CliCommandGuide> = {
+  memory: {
+    summary: 'Store, search, inspect, resolve, consolidate, and promote project memory.',
+    usage: [
+      'memorix memory search --query "timeout regression" [--limit 10]',
+      'memorix memory store --text "..." [--title "..."] [--visibility project|personal|team]',
+      'memorix memory detail --id 42',
+      'memorix memory recent [--limit 10]',
+      'memorix memory resolve --ids 42,43 [--status resolved|archived]',
+      'memorix memory consolidate --action preview|execute',
+      'memorix memory promote --ids 42,43 [--trigger "..."] [--instruction "..."]',
+    ],
+    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.',
+    usage: [
+      'memorix identity status',
+      'memorix identity join --agent-type codex [--name codex-main --instance-id local]',
+      'memorix identity use --agent-id <id>',
+      'memorix identity clear',
+    ],
+    notes: ['Without an identity, CLI reads and writes only project-visible memory.'],
+  },
+  session: {
+    summary: 'Start, end, and inspect coding sessions. Coordination remains opt-in.',
+    usage: [
+      'memorix session start --agent codex',
+      'memorix session start --agent codex --agent-type codex --join-team --use',
+      'memorix session end --session-id <id> [--summary "..."]',
+      'memorix session context [--limit 3]',
+    ],
+  },
+  context: {
+    summary: 'Build the bounded task Workset used to resume or begin real work.',
+    usage: ['memorix context --task "continue the release fix" [--refresh auto|always|never]'],
+  },
+  explain: {
+    summary: 'Show why a task context contains its current facts and memory evidence.',
+    usage: ['memorix explain [--refresh auto|always|never]'],
+  },
+  codegraph: {
+    summary: 'Refresh local code-state snapshots and assemble task-specific code context.',
+    usage: [
+      'memorix codegraph status',
+      'memorix codegraph refresh',
+      'memorix codegraph context-pack --task "trace the auth flow" [--limit 20]',
+    ],
+  },
+  knowledge: {
+    summary: 'Manage the reviewed, source-backed Knowledge Workspace and project workflows.',
+    usage: [
+      'memorix knowledge init [--mode local|versioned]',
+      'memorix knowledge status',
+      'memorix knowledge compile',
+      'memorix knowledge lint',
+      'memorix knowledge workflow list',
+    ],
+  },
+  reasoning: {
+    summary: 'Capture and retrieve engineering decision rationale.',
+    usage: [
+      'memorix reasoning store --entity auth --decision "Use SQLite" --rationale "..."',
+      'memorix reasoning search --query "why sqlite" [--scope project|global]',
+    ],
+  },
+  retention: {
+    summary: 'Inspect retention state and archive records that are eligible under the current scope.',
+    usage: [
+      'memorix retention status',
+      'memorix retention stale',
+      'memorix retention archive',
+    ],
+  },
+  transfer: {
+    summary: 'Create or restore explicit project memory snapshots for backup and automation.',
+    usage: [
+      'memorix transfer export --format json --out ./.memorix-export.json',
+      'memorix transfer import --file ./.memorix-export.json',
+      'memorix transfer import --stdin',
+    ],
+  },
+  team: {
+    summary: 'Manage explicit multi-agent coordination state for the current project.',
+    usage: [
+      'memorix team join --agent-type codex [--name codex-main]',
+      'memorix team status [--all]',
+      'memorix team leave [--agent-id <id>]',
+    ],
+  },
+  task: {
+    summary: 'Create and progress coordination tasks. An active CLI identity fills agentId automatically.',
+    usage: [
+      'memorix task create --description "Review release evidence"',
+      'memorix task claim --task-id <id>',
+      'memorix task complete --task-id <id> --result "Verified"',
+      'memorix task list [--available]',
+    ],
+  },
+  message: {
+    summary: 'Send and read coordination messages. An active CLI identity fills the sender automatically.',
+    usage: [
+      'memorix message send --to <agent-id> --type info --content "..."',
+      'memorix message broadcast --type announcement --content "..."',
+      'memorix message inbox [--mark-read]',
+    ],
+  },
+  lock: {
+    summary: 'Use advisory file locks to reduce overlapping edits between agents.',
+    usage: [
+      'memorix lock lock --file src/server.ts',
+      'memorix lock unlock --file src/server.ts',
+      'memorix lock status [--file src/server.ts]',
+    ],
+  },
+  handoff: {
+    summary: 'Create durable, targeted or team-visible handoff artifacts.',
+    usage: ['memorix handoff send --summary "..." --context "..." [--to-agent-id <id>]'],
+  },
+  poll: {
+    summary: 'Return a compact coordination snapshot for the active CLI identity.',
+    usage: ['memorix poll [--mark-inbox-read]'],
+  },
+  audit: {
+    summary: 'Inspect quality, attribution, and recorded audit evidence.',
+    usage: ['memorix audit memory', 'memorix audit project [--threshold 2]', 'memorix audit list'],
+  },
+  skills: {
+    summary: 'Inspect and generate project skills from project-visible memory evidence.',
+    usage: ['memorix skills list', 'memorix skills generate [--write --target codex]', 'memorix skills show --name <skill>'],
+  },
+  sync: {
+    summary: 'Synchronize agent rules and workspace artifacts through explicit routes.',
+    usage: ['memorix sync rules --action status', 'memorix sync workspace --action scan'],
+  },
+  ingest: {
+    summary: 'Ingest Git and image evidence into project memory.',
+    usage: ['memorix ingest commit [--ref HEAD]', 'memorix ingest log [--count 10]', 'memorix ingest image --path ./diagram.png'],
+  },
+  workbench: {
+    summary: 'Open the interactive terminal memory control plane.',
+    usage: ['memorix workbench'],
+  },
+};
+
+export function commandGuideNames(): string[] {
+  return Object.keys(GUIDES).sort();
+}
+
+export function renderCliGuide(command?: string): string {
+  const normalized = command?.trim().toLowerCase();
+  if (normalized && GUIDES[normalized]) {
+    const guide = GUIDES[normalized];
+    return [
+      `Memorix ${normalized}`,
+      '',
+      guide.summary,
+      '',
+      'Usage:',
+      ...guide.usage.map((line) => `  ${line}`),
+      ...(guide.notes?.length ? ['', ...guide.notes.map((line) => `Note: ${line}`)] : []),
+      '',
+      'Project/actor options: --cwd <git-project>  --as <active-agent-id>. Operator commands accept --json.',
+    ].join('\n');
+  }
+
+  return [
+    'Memorix CLI',
+    '',
+    'Use `memorix <command> --help` for an action-oriented guide.',
+    '',
+    `Command groups: ${commandGuideNames().join(', ')}`,
+    '',
+    'Global options: --cwd <git-project>  --as <active-agent-id>',
+    'Compatibility: camelCase flags remain supported; kebab-case flags are accepted too.',
+  ].join('\n');
+}
+
+/** Render manual action help before Citty consumes `--help` as flag metadata. */
+export function printCliGuideForHelp(argv: string[] = process.argv.slice(2)): boolean {
+  const [command, ...rest] = argv;
+  if (!command || !GUIDES[command.toLowerCase()]) return false;
+  if (!rest.includes('--help') && !rest.includes('-h')) return false;
+  console.log(renderCliGuide(command));
+  return true;
+}