memorix 1.1.13 → 1.2.1

package/src/knowledge/workspace-store.ts

@@ -0,0 +1,220 @@
+import { randomUUID } from 'node:crypto';
+import { getDatabase } from '../store/sqlite-db.js';
+import type {
+  KnowledgePageRecord,
+  KnowledgeProposal,
+  KnowledgeWorkspace,
+  KnowledgeWorkspaceMode,
+  KnowledgeWorkspaceStatus,
+} from './workspace-types.js';
+
+function arrayValue(raw: unknown): string[] {
+  if (typeof raw !== 'string' || !raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((item): item is string => typeof item === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+function optionalText(value: unknown): string | undefined {
+  return typeof value === 'string' && value ? value : undefined;
+}
+
+function rowToWorkspace(row: any): KnowledgeWorkspace {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    mode: row.mode,
+    rootPath: row.rootPath,
+    ...(optionalText(row.projectRoot) ? { projectRoot: row.projectRoot } : {}),
+    status: row.status,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    ...(optionalText(row.lastCompiledAt) ? { lastCompiledAt: row.lastCompiledAt } : {}),
+    ...(optionalText(row.lastLintedAt) ? { lastLintedAt: row.lastLintedAt } : {}),
+  };
+}
+
+function rowToPage(row: any): KnowledgePageRecord {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    relativePath: row.relativePath,
+    title: row.title,
+    kind: row.kind,
+    status: row.status,
+    reviewState: row.reviewState,
+    contentHash: row.contentHash,
+    sourceHash: row.sourceHash,
+    claimIds: arrayValue(row.claimIdsJson),
+    ...(optionalText(row.snapshotId) ? { snapshotId: row.snapshotId } : {}),
+    tags: arrayValue(row.tagsJson),
+    generatedAt: row.generatedAt,
+    updatedAt: row.updatedAt,
+    ...(optionalText(row.lastLintedAt) ? { lastLintedAt: row.lastLintedAt } : {}),
+    ...(optionalText(row.manualContentHash) ? { manualContentHash: row.manualContentHash } : {}),
+  };
+}
+
+function rowToProposal(row: any): KnowledgeProposal {
+  return {
+    id: row.id,
+    workspaceId: row.workspaceId,
+    pageId: row.pageId,
+    targetPath: row.targetPath,
+    proposalPath: row.proposalPath,
+    ...(optionalText(row.baseContentHash) ? { baseContentHash: row.baseContentHash } : {}),
+    sourceHash: row.sourceHash,
+    reason: row.reason,
+    status: row.status,
+    createdAt: row.createdAt,
+    ...(optionalText(row.appliedAt) ? { appliedAt: row.appliedAt } : {}),
+  };
+}
+
+/**
+ * Operational metadata for Markdown workspaces. The Markdown files remain the
+ * human-readable source; this store tracks provenance and safe proposal state.
+ */
+export class KnowledgeWorkspaceStore {
+  private db: any = null;
+
+  async init(dataDir: string): Promise<void> {
+    this.db = getDatabase(dataDir);
+  }
+
+  upsertWorkspace(input: Omit<KnowledgeWorkspace, 'createdAt' | 'updatedAt'> & {
+    createdAt?: string;
+    updatedAt?: string;
+  }): KnowledgeWorkspace {
+    const now = input.updatedAt ?? new Date().toISOString();
+    const createdAt = input.createdAt ?? now;
+    this.db.prepare(
+      'INSERT INTO knowledge_workspaces (id, projectId, mode, rootPath, projectRoot, status, createdAt, updatedAt, lastCompiledAt, lastLintedAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET mode = excluded.mode, rootPath = excluded.rootPath, projectRoot = excluded.projectRoot, status = excluded.status, updatedAt = excluded.updatedAt, lastCompiledAt = excluded.lastCompiledAt, lastLintedAt = excluded.lastLintedAt',
+    ).run(
+      input.id,
+      input.projectId,
+      input.mode,
+      input.rootPath,
+      input.projectRoot ?? null,
+      input.status,
+      createdAt,
+      now,
+      input.lastCompiledAt ?? null,
+      input.lastLintedAt ?? null,
+    );
+    return this.getWorkspace(input.id)!;
+  }
+
+  getWorkspace(id: string): KnowledgeWorkspace | undefined {
+    const row = this.db.prepare('SELECT * FROM knowledge_workspaces WHERE id = ?').get(id);
+    return row ? rowToWorkspace(row) : undefined;
+  }
+
+  findWorkspace(projectId: string, mode: KnowledgeWorkspaceMode): KnowledgeWorkspace | undefined {
+    const row = this.db.prepare('SELECT * FROM knowledge_workspaces WHERE projectId = ? AND mode = ? ORDER BY updatedAt DESC LIMIT 1').get(projectId, mode);
+    return row ? rowToWorkspace(row) : undefined;
+  }
+
+  upsertPage(page: KnowledgePageRecord): void {
+    this.db.prepare(
+      'INSERT INTO knowledge_pages (id, workspaceId, relativePath, title, kind, status, reviewState, contentHash, sourceHash, claimIdsJson, snapshotId, tagsJson, generatedAt, updatedAt, lastLintedAt, manualContentHash) VALUES (@id, @workspaceId, @relativePath, @title, @kind, @status, @reviewState, @contentHash, @sourceHash, @claimIdsJson, @snapshotId, @tagsJson, @generatedAt, @updatedAt, @lastLintedAt, @manualContentHash) ON CONFLICT(workspaceId, relativePath) DO UPDATE SET id = excluded.id, title = excluded.title, kind = excluded.kind, status = excluded.status, reviewState = excluded.reviewState, contentHash = excluded.contentHash, sourceHash = excluded.sourceHash, claimIdsJson = excluded.claimIdsJson, snapshotId = excluded.snapshotId, tagsJson = excluded.tagsJson, generatedAt = excluded.generatedAt, updatedAt = excluded.updatedAt, lastLintedAt = excluded.lastLintedAt, manualContentHash = excluded.manualContentHash',
+    ).run({
+      ...page,
+      claimIdsJson: JSON.stringify(page.claimIds),
+      snapshotId: page.snapshotId ?? null,
+      tagsJson: JSON.stringify(page.tags),
+      lastLintedAt: page.lastLintedAt ?? null,
+      manualContentHash: page.manualContentHash ?? null,
+    });
+  }
+
+  getPage(workspaceId: string, relativePath: string): KnowledgePageRecord | undefined {
+    const row = this.db.prepare('SELECT * FROM knowledge_pages WHERE workspaceId = ? AND relativePath = ?').get(workspaceId, relativePath);
+    return row ? rowToPage(row) : undefined;
+  }
+
+  getPageById(id: string): KnowledgePageRecord | undefined {
+    const row = this.db.prepare('SELECT * FROM knowledge_pages WHERE id = ?').get(id);
+    return row ? rowToPage(row) : undefined;
+  }
+
+  listPages(workspaceId: string): KnowledgePageRecord[] {
+    return this.db.prepare('SELECT * FROM knowledge_pages WHERE workspaceId = ? ORDER BY relativePath').all(workspaceId).map(rowToPage);
+  }
+
+  replacePageClaims(pageId: string, claimIds: string[]): void {
+    const remove = this.db.prepare('DELETE FROM knowledge_page_claims WHERE pageId = ?');
+    const insert = this.db.prepare("INSERT OR IGNORE INTO knowledge_page_claims (pageId, claimId, role) VALUES (?, ?, 'primary')");
+    this.db.transaction(() => {
+      remove.run(pageId);
+      for (const claimId of [...new Set(claimIds)]) insert.run(pageId, claimId);
+    })();
+  }
+
+  replacePageLinks(pageId: string, targets: string[]): void {
+    const remove = this.db.prepare('DELETE FROM knowledge_page_links WHERE sourcePageId = ?');
+    const insert = this.db.prepare('INSERT OR IGNORE INTO knowledge_page_links (sourcePageId, targetPath) VALUES (?, ?)');
+    this.db.transaction(() => {
+      remove.run(pageId);
+      for (const target of [...new Set(targets)]) insert.run(pageId, target);
+    })();
+  }
+
+  createProposal(input: Omit<KnowledgeProposal, 'id' | 'createdAt' | 'status'> & {
+    id?: string;
+    createdAt?: string;
+    status?: KnowledgeProposal['status'];
+  }): KnowledgeProposal {
+    const proposal: KnowledgeProposal = {
+      id: input.id ?? randomUUID(),
+      ...input,
+      status: input.status ?? 'pending',
+      createdAt: input.createdAt ?? new Date().toISOString(),
+    };
+    this.db.prepare(
+      'INSERT INTO knowledge_proposals (id, workspaceId, pageId, targetPath, proposalPath, baseContentHash, sourceHash, reason, status, createdAt, appliedAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(workspaceId, proposalPath) DO UPDATE SET pageId = excluded.pageId, targetPath = excluded.targetPath, baseContentHash = excluded.baseContentHash, sourceHash = excluded.sourceHash, reason = excluded.reason, status = excluded.status, createdAt = excluded.createdAt, appliedAt = excluded.appliedAt',
+    ).run(
+      proposal.id,
+      proposal.workspaceId,
+      proposal.pageId,
+      proposal.targetPath,
+      proposal.proposalPath,
+      proposal.baseContentHash ?? null,
+      proposal.sourceHash,
+      proposal.reason,
+      proposal.status,
+      proposal.createdAt,
+      proposal.appliedAt ?? null,
+    );
+    const row = this.db.prepare('SELECT * FROM knowledge_proposals WHERE workspaceId = ? AND proposalPath = ?').get(proposal.workspaceId, proposal.proposalPath);
+    return rowToProposal(row);
+  }
+
+  getProposal(id: string): KnowledgeProposal | undefined {
+    const row = this.db.prepare('SELECT * FROM knowledge_proposals WHERE id = ?').get(id);
+    return row ? rowToProposal(row) : undefined;
+  }
+
+  listProposals(workspaceId: string, status?: KnowledgeProposal['status']): KnowledgeProposal[] {
+    const rows = status
+      ? this.db.prepare('SELECT * FROM knowledge_proposals WHERE workspaceId = ? AND status = ? ORDER BY createdAt DESC, id').all(workspaceId, status)
+      : this.db.prepare('SELECT * FROM knowledge_proposals WHERE workspaceId = ? ORDER BY createdAt DESC, id').all(workspaceId);
+    return rows.map(rowToProposal);
+  }
+
+  markProposalApplied(id: string, appliedAt = new Date().toISOString()): KnowledgeProposal {
+    this.db.prepare("UPDATE knowledge_proposals SET status = 'applied', appliedAt = ? WHERE id = ?").run(appliedAt, id);
+    return this.getProposal(id)!;
+  }
+
+  markWorkspaceCompiled(id: string, at = new Date().toISOString()): void {
+    this.db.prepare('UPDATE knowledge_workspaces SET lastCompiledAt = ?, updatedAt = ? WHERE id = ?').run(at, at, id);
+  }
+
+  markWorkspaceLinted(id: string, status: KnowledgeWorkspaceStatus, at = new Date().toISOString()): void {
+    this.db.prepare('UPDATE knowledge_workspaces SET status = ?, lastLintedAt = ?, updatedAt = ? WHERE id = ?').run(status, at, at, id);
+  }
+}

package/src/knowledge/workspace-types.ts

@@ -0,0 +1,106 @@
+export type KnowledgeWorkspaceMode = 'local' | 'versioned';
+export type KnowledgeWorkspaceStatus = 'ready' | 'needs-review' | 'error';
+
+export interface KnowledgeWorkspace {
+  id: string;
+  projectId: string;
+  /** Local Memorix data directory used for the operational SQLite index. */
+  dataDir?: string;
+  mode: KnowledgeWorkspaceMode;
+  rootPath: string;
+  projectRoot?: string;
+  status: KnowledgeWorkspaceStatus;
+  createdAt: string;
+  updatedAt: string;
+  lastCompiledAt?: string;
+  lastLintedAt?: string;
+}
+
+export type KnowledgePageKind = 'topic' | 'decision' | 'risk' | 'index' | 'schema' | 'log';
+export type KnowledgePageStatus = 'active' | 'proposed';
+export type KnowledgePageReviewState = 'approved' | 'needs-review';
+
+export interface KnowledgePageFrontmatter {
+  id: string;
+  title: string;
+  kind: KnowledgePageKind;
+  status: KnowledgePageStatus;
+  reviewState: KnowledgePageReviewState;
+  claimIds: string[];
+  evidenceRefs: string[];
+  snapshotId?: string;
+  tags: string[];
+  sourceHash: string;
+  generatedAt: string;
+  updatedAt: string;
+}
+
+export interface KnowledgePage {
+  absolutePath: string;
+  relativePath: string;
+  frontmatter: KnowledgePageFrontmatter;
+  body: string;
+  contentHash: string;
+  links: string[];
+}
+
+export interface KnowledgePageRecord {
+  id: string;
+  workspaceId: string;
+  relativePath: string;
+  title: string;
+  kind: KnowledgePageKind;
+  status: KnowledgePageStatus;
+  reviewState: KnowledgePageReviewState;
+  contentHash: string;
+  sourceHash: string;
+  claimIds: string[];
+  snapshotId?: string;
+  tags: string[];
+  generatedAt: string;
+  updatedAt: string;
+  lastLintedAt?: string;
+  manualContentHash?: string;
+}
+
+export type KnowledgeProposalReason = 'new-page' | 'source-changed' | 'manual-edit-protected';
+export type KnowledgeProposalStatus = 'pending' | 'applied' | 'superseded';
+
+export interface KnowledgeProposal {
+  id: string;
+  workspaceId: string;
+  pageId: string;
+  targetPath: string;
+  proposalPath: string;
+  baseContentHash?: string;
+  sourceHash: string;
+  reason: KnowledgeProposalReason;
+  status: KnowledgeProposalStatus;
+  createdAt: string;
+  appliedAt?: string;
+}
+
+export type WikiLintIssueKind =
+  | 'malformed-frontmatter'
+  | 'broken-link'
+  | 'orphan-page'
+  | 'missing-claim'
+  | 'missing-evidence'
+  | 'superseded-claim'
+  | 'unresolved-conflict'
+  | 'stale-snapshot'
+  | 'manual-edit-protected';
+
+export interface WikiLintIssue {
+  kind: WikiLintIssueKind;
+  severity: 'error' | 'warning';
+  message: string;
+  relativePath?: string;
+  claimId?: string;
+}
+
+export interface WikiLintResult {
+  valid: boolean;
+  pagesScanned: number;
+  issues: WikiLintIssue[];
+}

package/src/knowledge/workspace.ts

@@ -0,0 +1,220 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { atomicWriteFile, withFileLock } from '../store/file-lock.js';
+import { KnowledgeWorkspaceStore } from './workspace-store.js';
+import type { KnowledgeWorkspace, KnowledgeWorkspaceMode } from './workspace-types.js';
+
+const execFileAsync = promisify(execFile);
+
+export interface KnowledgeWorkspacePaths {
+  root: string;
+  pages: string;
+  proposals: string;
+  workflows: string;
+  index: string;
+  log: string;
+  schema: string;
+}
+
+export interface InitializeKnowledgeWorkspaceInput {
+  projectId: string;
+  dataDir: string;
+  mode: KnowledgeWorkspaceMode;
+  projectRoot?: string;
+  rootPath?: string;
+}
+
+function hash(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function workspaceId(projectId: string, mode: KnowledgeWorkspaceMode): string {
+  return 'workspace:' + hash(projectId + ':' + mode).slice(0, 24);
+}
+
+function localWorkspacePath(dataDir: string, projectId: string): string {
+  return path.join(path.resolve(dataDir), 'knowledge-workspaces', hash(projectId).slice(0, 24));
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative !== '' && !relative.startsWith('..' + path.sep) && relative !== '..' && !path.isAbsolute(relative);
+}
+
+function ensureVersionedPath(projectRoot: string, rootPath: string): string {
+  if (!path.isAbsolute(rootPath)) {
+    throw new Error('A versioned knowledge workspace requires an explicit absolute path');
+  }
+  const resolvedProject = path.resolve(projectRoot);
+  const resolvedWorkspace = path.resolve(rootPath);
+  if (!isWithin(resolvedProject, resolvedWorkspace)) {
+    throw new Error('A versioned knowledge workspace must live inside the Git project');
+  }
+  const segments = path.relative(resolvedProject, resolvedWorkspace).split(path.sep);
+  if (segments.includes('.git') || segments.includes('node_modules') || segments.includes('dist')) {
+    throw new Error('The selected knowledge workspace path is not safe for project artifacts');
+  }
+  return resolvedWorkspace;
+}
+
+async function isIgnoredByGit(projectRoot: string, workspaceRoot: string): Promise<boolean> {
+  const relative = path.relative(projectRoot, workspaceRoot).split(path.sep).join('/');
+  const probes = [relative, relative.replace(/\/+$/, '') + '/.memorix-workspace-probe'];
+  for (const probe of probes) {
+    try {
+      await execFileAsync('git', ['-C', projectRoot, 'check-ignore', '--quiet', '--no-index', '--', probe], {
+        timeout: 3_000,
+        windowsHide: true,
+      });
+      return true;
+    } catch (error) {
+      const code = error && typeof error === 'object' && 'code' in error
+        ? (error as { code?: number | string }).code
+        : undefined;
+      if (code === 1 || code === '1') continue;
+      return false;
+    }
+  }
+  return false;
+}
+
+async function assertNoSymlinkEscape(projectRoot: string, workspaceRoot: string): Promise<void> {
+  const [realProject, realWorkspace] = await Promise.all([
+    fs.realpath(projectRoot),
+    fs.realpath(workspaceRoot),
+  ]);
+  if (!isWithin(realProject, realWorkspace)) {
+    throw new Error('The selected knowledge workspace resolves outside the Git project');
+  }
+}
+
+export function getKnowledgeWorkspacePaths(workspace: Pick<KnowledgeWorkspace, 'rootPath'>): KnowledgeWorkspacePaths {
+  const root = path.resolve(workspace.rootPath);
+  return {
+    root,
+    pages: path.join(root, 'pages'),
+    proposals: path.join(root, 'proposals'),
+    workflows: path.join(root, 'workflows'),
+    index: path.join(root, 'index.md'),
+    log: path.join(root, 'log.md'),
+    schema: path.join(root, 'schema.md'),
+  };
+}
+
+export function resolveKnowledgeWorkspaceFile(workspace: Pick<KnowledgeWorkspace, 'rootPath'>, relativePath: string): string {
+  if (!relativePath || path.isAbsolute(relativePath)) {
+    throw new Error('Knowledge workspace paths must be relative');
+  }
+  const root = path.resolve(workspace.rootPath);
+  const candidate = path.resolve(root, relativePath);
+  if (candidate === root || !isWithin(root, candidate)) {
+    throw new Error('Knowledge workspace path escapes its root');
+  }
+  return candidate;
+}
+
+async function writeIfMissing(filePath: string, content: string): Promise<void> {
+  try {
+    await fs.access(filePath);
+  } catch {
+    await atomicWriteFile(filePath, content);
+  }
+}
+
+function schemaContent(): string {
+  return [
+    '# Memorix Knowledge Workspace',
+    '',
+    'This workspace is compiled from source-qualified Memorix claims.',
+    'Topic pages are proposal-first: review and apply a proposal before relying',
+    'on it as a published project knowledge page.',
+    '',
+    'Do not remove claim ids, evidence references, source hashes, or snapshot',
+    'references from page frontmatter. Manual body edits are preserved and cause',
+    'later compiler output to remain a proposal.',
+    '',
+  ].join('\n');
+}
+
+function indexContent(): string {
+  return [
+    '# Knowledge Workspace',
+    '',
+    '## Published pages',
+    '',
+    'No published pages yet.',
+    '',
+    '## Review queue',
+    '',
+    'No pending proposals.',
+    '',
+  ].join('\n');
+}
+
+function logContent(): string {
+  return '# Knowledge log\n\n';
+}
+
+export async function initializeKnowledgeWorkspace(input: InitializeKnowledgeWorkspaceInput): Promise<KnowledgeWorkspace> {
+  if (!input.projectId.trim()) throw new Error('Knowledge workspace project id is required');
+  if (!input.dataDir.trim()) throw new Error('Knowledge workspace data directory is required');
+
+  let rootPath: string;
+  let projectRoot: string | undefined;
+  if (input.mode === 'local') {
+    rootPath = localWorkspacePath(input.dataDir, input.projectId);
+  } else {
+    if (!input.projectRoot || !input.rootPath) {
+      throw new Error('A versioned knowledge workspace requires projectRoot and rootPath');
+    }
+    projectRoot = path.resolve(input.projectRoot);
+    rootPath = ensureVersionedPath(projectRoot, input.rootPath);
+    if (await isIgnoredByGit(projectRoot, rootPath)) {
+      throw new Error('The selected versioned knowledge workspace is ignored by Git');
+    }
+  }
+
+  const paths = getKnowledgeWorkspacePaths({ rootPath });
+  await fs.mkdir(paths.pages, { recursive: true });
+  await Promise.all([
+    fs.mkdir(paths.proposals, { recursive: true }),
+    fs.mkdir(paths.workflows, { recursive: true }),
+  ]);
+  if (projectRoot) await assertNoSymlinkEscape(projectRoot, paths.root);
+
+  const workspace: KnowledgeWorkspace = {
+    id: workspaceId(input.projectId, input.mode),
+    projectId: input.projectId,
+    dataDir: path.resolve(input.dataDir),
+    mode: input.mode,
+    rootPath: paths.root,
+    ...(projectRoot ? { projectRoot } : {}),
+    status: 'ready',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  };
+
+  await withFileLock(paths.root, async () => {
+    await writeIfMissing(paths.schema, schemaContent());
+    await writeIfMissing(paths.index, indexContent());
+    await writeIfMissing(paths.log, logContent());
+  });
+
+  const store = new KnowledgeWorkspaceStore();
+  await store.init(input.dataDir);
+  return { ...store.upsertWorkspace(workspace), dataDir: workspace.dataDir };
+}
+
+export async function loadKnowledgeWorkspace(input: {
+  projectId: string;
+  dataDir: string;
+  mode?: KnowledgeWorkspaceMode;
+}): Promise<KnowledgeWorkspace | undefined> {
+  const store = new KnowledgeWorkspaceStore();
+  await store.init(input.dataDir);
+  const workspace = store.findWorkspace(input.projectId, input.mode ?? 'local');
+  return workspace ? { ...workspace, dataDir: path.resolve(input.dataDir) } : undefined;
+}

package/src/memory/auto-relations.ts

@@ -56,6 +56,27 @@ export async function createAutoRelations(
   // Skip self-references
   const selfName = obs.entityName.toLowerCase();
 
+  const explicitRelated = [...new Set((obs.relatedEntities ?? [])
+    .map(name => name.trim())
+    .filter(name => name && name.toLowerCase() !== selfName))];
+  if (explicitRelated.length > 0) {
+    await graphManager.createEntities(explicitRelated.map(name => ({
+      name,
+      entityType: 'related',
+      observations: [],
+    })));
+    for (const name of explicitRelated) {
+      const matchedEntity = graphManager.findEntityByName(name);
+      if (matchedEntity) {
+        relations.push({
+          from: obs.entityName,
+          to: matchedEntity.name,
+          relationType: 'related_entity',
+        });
+      }
+    }
+  }
+
   // Check extracted identifiers against existing entities (O(1) lookups via index)
   const candidates = [
     ...extracted.identifiers,

package/src/memory/graph-scope.ts

@@ -0,0 +1,46 @@
+export interface GraphScopeObservation {
+  entityName?: string;
+  relatedEntities?: string[];
+  status?: string;
+}
+
+export interface ScopedKnowledgeGraph<Entity extends { name: string }, Relation extends { from: string; to: string }> {
+  entities: Entity[];
+  relations: Relation[];
+  entityNames: Set<string>;
+}
+
+/** Return the active project entities, including explicit cross-references. */
+export function projectGraphEntityNames(observations: readonly GraphScopeObservation[]): Set<string> {
+  const entityNames = new Set<string>();
+  for (const observation of observations) {
+    if ((observation.status ?? 'active') !== 'active') continue;
+    const entityName = observation.entityName?.trim();
+    if (entityName) entityNames.add(entityName);
+    for (const relatedEntity of observation.relatedEntities ?? []) {
+      const name = relatedEntity.trim();
+      if (name) entityNames.add(name);
+    }
+  }
+  return entityNames;
+}
+
+/**
+ * Give every graph surface the same project projection: active entities plus
+ * explicit related entities, with only edges whose endpoints remain visible.
+ */
+export function scopeKnowledgeGraphToProject<
+  Entity extends { name: string },
+  Relation extends { from: string; to: string },
+>(
+  graph: { entities: readonly Entity[]; relations: readonly Relation[] },
+  observations: readonly GraphScopeObservation[],
+): ScopedKnowledgeGraph<Entity, Relation> {
+  const entityNames = projectGraphEntityNames(observations);
+  const entities = graph.entities.filter(entity => entityNames.has(entity.name));
+  const visibleNames = new Set(entities.map(entity => entity.name));
+  const relations = graph.relations.filter(relation =>
+    visibleNames.has(relation.from) && visibleNames.has(relation.to),
+  );
+  return { entities, relations, entityNames };
+}

package/src/memory/observations.ts

@@ -31,6 +31,7 @@ import { countTextTokens } from '../compact/token-budget.js';
 import { extractEntities, enrichConcepts } from './entity-extractor.js';
 import { getEmbeddingProvider, isEmbeddingExplicitlyDisabled } from '../embedding/provider.js';
 import { sanitizeCredentials } from './secret-filter.js';
+import { enqueueClaimDerivation } from '../runtime/lifecycle.js';
 
 /** In-memory observation list (loaded from persistence on init) */
 let observations: Observation[] = [];
@@ -120,6 +121,22 @@ async function bindObservationCodeRefsBestEffort(observation: Observation): Prom
   }
 }
 
+function queueClaimDerivation(observation: Observation): void {
+  const dataDir = projectDir;
+  const isExplicit = observation.sourceDetail === 'explicit';
+  const isGit = observation.source === 'git' || observation.sourceDetail === 'git-ingest';
+  if (!dataDir || (!isExplicit && !isGit)) return;
+  try {
+    enqueueClaimDerivation({
+      dataDir,
+      projectId: observation.projectId,
+      observationId: observation.id,
+    });
+  } catch {
+    // The observation remains durable; a later scan can recover its claim.
+  }
+}
+
 function isVectorCompatibleWithCurrentIndex(embedding: number[] | null): boolean {
   if (!embedding) return false;
   const vectorDimensions = getVectorDimensions();
@@ -431,6 +448,7 @@ export async function storeObservation(input: {
   }
 
   await bindObservationCodeRefsBestEffort(observation);
+  queueClaimDerivation(observation);
 
   // Generate embedding async (fire-and-forget) — never blocks MCP response
   // Track in vectorMissingIds until embedding is successfully written.
@@ -585,6 +603,7 @@ async function upsertObservation(
   }
 
   await bindObservationCodeRefsBestEffort(existing);
+  queueClaimDerivation(existing);
 
   // Generate embedding async (fire-and-forget) — never blocks MCP response
   const searchableText = [input.title, input.narrative, ...(input.facts ?? [])].join(' ');