memorix 1.2.10 → 1.3.0

package/src/embedding/provider.ts

@@ -27,15 +27,22 @@
  * Architecture inspired by Mem0's multi-provider embedding design.
  */
 
+export interface EmbeddingRequestOptions {
+  /** Bound one remote embedding request without changing the provider default. */
+  timeoutMs?: number;
+  /** Disable provider retries for latency-sensitive best-effort work. */
+  retry?: boolean;
+}
+
 export interface EmbeddingProvider {
   /** Provider name for logging/cache keys */
   readonly name: string;
   /** Vector dimensions (e.g., 384 for bge-small) */
   readonly dimensions: number;
   /** Generate embedding for a single text */
-  embed(text: string): Promise<number[]>;
+  embed(text: string, options?: EmbeddingRequestOptions): Promise<number[]>;
   /** Generate embeddings for multiple texts (batch) */
-  embedBatch(texts: string[]): Promise<number[][]>;
+  embedBatch(texts: string[], options?: EmbeddingRequestOptions): Promise<number[][]>;
   /** Return already-persisted embeddings without generating new vectors. */
   getCachedEmbeddings?(texts: string[]): Promise<(number[] | null)[]>;
 }
@@ -43,6 +50,10 @@ export interface EmbeddingProvider {
 export interface GetEmbeddingProviderOptions {
   /** Avoid remote API dimension probes while preparing a startup index. */
   allowNetworkProbe?: boolean;
+  /** Bound a remote API dimension probe for a latency-sensitive caller. */
+  requestTimeoutMs?: number;
+  /** Disable retries while resolving a best-effort provider. */
+  retry?: boolean;
 }
 
 /** Singleton provider instance (null = not available) */
@@ -205,9 +216,9 @@ function wrapProvider(candidate: EmbeddingProvider): EmbeddingProvider {
   return {
     name: candidate.name,
     dimensions: candidate.dimensions,
-    async embed(text: string): Promise<number[]> {
+    async embed(text: string, options?: EmbeddingRequestOptions): Promise<number[]> {
       try {
-        return await candidate.embed(text);
+        return await candidate.embed(text, options);
       } catch (error) {
         if (kind === 'api' && getEmbeddingMode() === 'auto' && isTemporaryEmbeddingFailure(error)) {
           warnOnce('[memorix] API embedding temporarily unavailable — switching to local fallback provider');
@@ -215,7 +226,7 @@ function wrapProvider(candidate: EmbeddingProvider): EmbeddingProvider {
           if (fallback) {
             provider = wrapProvider(fallback);
             warnOnce(`[memorix] Embedding fallback activated: ${provider.name} (${provider.dimensions}d)`);
-            return provider.embed(text);
+            return provider.embed(text, options);
           }
         }
 
@@ -225,9 +236,9 @@ function wrapProvider(candidate: EmbeddingProvider): EmbeddingProvider {
         throw error;
       }
     },
-    async embedBatch(texts: string[]): Promise<number[][]> {
+    async embedBatch(texts: string[], options?: EmbeddingRequestOptions): Promise<number[][]> {
       try {
-        return await candidate.embedBatch(texts);
+        return await candidate.embedBatch(texts, options);
       } catch (error) {
         if (kind === 'api' && getEmbeddingMode() === 'auto' && isTemporaryEmbeddingFailure(error)) {
           warnOnce('[memorix] API embedding temporarily unavailable — switching to local fallback provider');
@@ -235,7 +246,7 @@ function wrapProvider(candidate: EmbeddingProvider): EmbeddingProvider {
           if (fallback) {
             provider = wrapProvider(fallback);
             warnOnce(`[memorix] Embedding fallback activated: ${provider.name} (${provider.dimensions}d)`);
-            return provider.embedBatch(texts);
+            return provider.embedBatch(texts, options);
           }
         }
 
@@ -331,7 +342,7 @@ export async function getEmbeddingProvider(
 
     // API mode: remote embedding via OpenAI-compatible endpoint
     if (mode === 'api') {
-      const initialized = await createAPIProvider();
+      const initialized = await createAPIProvider(options);
       if (!initialized) return null;
       provider = wrapProvider(initialized);
       warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);
@@ -340,7 +351,7 @@ export async function getEmbeddingProvider(
 
     // Auto mode: try configured API first, then local fallbacks
     if (hasAPIEmbeddingConfig()) {
-      const initialized = await createAPIProvider();
+      const initialized = await createAPIProvider(options);
       if (initialized) {
         provider = wrapProvider(initialized);
         warnOnce(`[memorix] Embedding provider: ${provider.name} (${provider.dimensions}d)`);

package/src/hooks/installers/index.ts

@@ -1247,6 +1247,8 @@ function getAgentRulesContent(agent?: AgentName, scope: 'project' | 'global' = '
     '- Include \x60filesModified\x60 when relevant',
     '- Use \x60topicKey\x60 for topics that evolve over time (prevents duplicates)',
     '- For "why" decisions, use \x60memorix_store_reasoning\x60',
+    '- For a stable fact, reusable procedure, or completed episode that merits deliberate long-term review, include \x60longTerm\x60 in \x60memorix_store\x60 with the appropriate kind and normally \x60scope: "project"\x60. It creates a candidate only: do not use it for routine updates, do not make project-derived evidence portable user memory, and do not assume it enters context until an operator qualifies and approves it through \x60memorix memory long-term\x60.',
+    '- A \x60user\x60 + \x60portable\x60 durable memory delivered in a task brief is intentionally available across projects. When it matches the task, use it as reusable background even if its origin differs; do not treat it as a current-project fact. Expand it only when needed with \x60memorix_detail\x60 using its \x60durable:<id>\x60 reference and a specific purpose.',
     '',
     "**Don't store:** greetings, simple file reads, trivial commands (ls, pwd, git status).",
     '',

package/src/knowledge/context-assembly.ts

@@ -18,6 +18,7 @@ export type ContextCandidateKind =
   | 'semantic-code'
   | 'start-here'
   | 'memory'
+  | 'durable-memory'
   | 'claim'
   | 'knowledge-page'
   | 'workflow'
@@ -43,7 +44,7 @@ export interface ContextReceiptOmission {
 }
 
 export interface ContextReceipt {
-  version: '1.2.4';
+  version: '1.3';
   target: ContextDeliveryTarget;
   elapsedMs: number;
   budget: {

package/src/knowledge/workset.ts

@@ -6,6 +6,7 @@ import { KnowledgeWorkspaceStore } from './workspace-store.js';
 import { loadKnowledgeWorkspace } from './workspace.js';
 import { WorkflowStore } from './workflow-store.js';
 import { selectWorkflows } from './workflows.js';
+import { renderLongTermMemorySummary, selectLongTermMemoriesForTask } from '../memory/long-term.js';
 import type {
   ContextCandidateFreshness,
   ContextCandidateKind,
@@ -18,6 +19,8 @@ import type { CodeGraphProviderQuality, ExternalCodeGraphOutline } from '../code
 import type { KnowledgeClaim, ClaimEvidenceRef } from './types.js';
 import type { KnowledgePageRecord, KnowledgeWorkspace } from './workspace-types.js';
 import type { WorkflowSelection } from './workflow-types.js';
+import type { ObservationReader } from '../types.js';
+import type { LongTermMemory, LongTermMemoryEvidence } from '../memory/long-term-types.js';
 
 export type WorksetCautionKind =
   | 'dirty-worktree'
@@ -77,6 +80,18 @@ export interface WorksetMemorySource {
   reason?: string;
 }
 
+/** A task-matching curated long-term item. The full record stays behind CLI detail. */
+export interface WorksetLongTermMemory {
+  id: string;
+  kind: LongTermMemory['kind'];
+  scope: LongTermMemory['scope'];
+  state: LongTermMemory['state'];
+  title: string;
+  summary: string;
+  evidenceRefs: string[];
+  reason: string;
+}
+
 /** Prior-work evidence selected only for an explicit or inferred continuation. */
 export interface WorksetContinuation {
   previousSession?: {
@@ -103,7 +118,7 @@ export interface WorksetContinuation {
 }
 
 export interface TaskWorkset {
-  version: '1.2';
+  version: '1.3';
   task: string;
   lens: string;
   currentFacts: string[];
@@ -117,6 +132,7 @@ export interface TaskWorkset {
   hiddenCautionMemoryCount: number;
   claims: WorksetClaim[];
   pages: WorksetPage[];
+  durableMemory: WorksetLongTermMemory[];
   workflows: WorksetWorkflow[];
   cautions: WorksetCaution[];
   verification: string[];
@@ -164,6 +180,8 @@ export interface BuildTaskWorksetInput {
     stale: number;
   };
   runtimeCautions?: WorksetCaution[];
+  /** Reader identity used only for team-scoped durable memory filtering. */
+  reader?: ObservationReader;
   maxTokens?: number;
   /** Delivery surface controls receipt semantics without changing prompt shape. */
   deliveryTarget?: ContextDeliveryTarget;
@@ -297,6 +315,7 @@ function receiptOmissionKind(raw: string): ContextCandidateKind | undefined {
   if (raw.includes('state')) return 'code-state';
   if (raw.includes('semantic')) return 'semantic-code';
   if (raw.includes('start')) return 'start-here';
+  if (raw.includes('durable-memory')) return 'durable-memory';
   if (raw.includes('memory')) return 'memory';
   if (raw.includes('claim')) return 'claim';
   if (raw.includes('knowledge-page')) return 'knowledge-page';
@@ -593,6 +612,27 @@ export function renderTaskWorksetPrompt(input: Omit<TaskWorkset, 'prompt' | 'bud
     }
   }
 
+  if (input.durableMemory.length > 0) {
+    appendLine(lines, '', maxTokens, omitted, 'durable-memory-heading');
+    appendLine(lines, 'Durable memory', maxTokens, omitted, 'durable-memory-heading');
+    for (const memory of input.durableMemory.slice(0, 3)) {
+      appendLine(
+        lines,
+        '- ' + memory.kind + ' (' + memory.scope + ', ' + memory.state + '; ref durable:' + memory.id + '): ' + memory.summary,
+        maxTokens,
+        omitted,
+        'durable-memory',
+        selected,
+        {
+          kind: 'durable-memory',
+          id: 'durable:' + memory.id,
+          reason: memory.reason,
+          trust: 'source-backed',
+        },
+      );
+    }
+  }
+
   if (input.workflows.length > 0) {
     appendLine(lines, '', maxTokens, omitted, 'workflow-heading');
     appendLine(lines, 'Project workflow', maxTokens, omitted, 'workflow-heading');
@@ -674,6 +714,35 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
     reason: selection.reasons[claim.id] ?? 'source-qualified task match',
   }));
 
+  let durableMemory: WorksetLongTermMemory[] = [];
+  let durableEvidence: LongTermMemoryEvidence[] = [];
+  if (task) {
+    try {
+      const selected = await selectLongTermMemoriesForTask({
+        dataDir: input.dataDir,
+        projectId: input.projectId,
+        task,
+        ...(input.reader?.agentId ? { agentId: input.reader.agentId } : {}),
+        ...(input.reader?.isTeamMember ? { isTeamMember: true } : {}),
+        limit: 3,
+      });
+      durableMemory = selected.map(item => ({
+        id: item.memory.id,
+        kind: item.memory.kind,
+        scope: item.memory.scope,
+        state: item.memory.state,
+        title: item.memory.title,
+        summary: renderLongTermMemorySummary(item.memory, 20),
+        evidenceRefs: item.evidence.map(evidence => evidence.id),
+        reason: item.reason,
+      }));
+      durableEvidence = selected.flatMap(item => item.evidence);
+    } catch {
+      // Long-term memory is optional enrichment; a local identity or schema
+      // problem must never block current source/code context delivery.
+    }
+  }
+
   let workspace: KnowledgeWorkspace | undefined;
   let pages: WorksetPage[] = [];
   let workflows: WorksetWorkflow[] = [];
@@ -719,7 +788,10 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
   const evidenceIds = unique(selection.claims.flatMap(claim => evidenceIdsForClaim(
     claim,
     evidenceByClaim.get(claim.id) ?? [],
-  )));
+  )).concat(
+    durableMemory.map(memory => 'durable:' + memory.id),
+    durableEvidence.map(evidence => 'durable-evidence:' + evidence.id),
+  ));
   const verification = unique([
     ...workflows.flatMap(workflow => workflow.verificationGates),
     ...input.verificationHints,
@@ -758,7 +830,7 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
     }
     : undefined;
   const base = {
-    version: '1.2' as const,
+    version: '1.3' as const,
     task,
     lens: input.lens,
     currentFacts: input.currentFacts?.map(fact => fact.startsWith('Historical note:')
@@ -773,6 +845,7 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
     hiddenCautionMemoryCount: input.hiddenCautionMemoryCount ?? 0,
     claims,
     pages,
+    durableMemory,
     workflows,
     cautions: normalizedCautions,
     verification,
@@ -789,7 +862,7 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
     budget: { maxTokens },
   });
   const receipt: ContextReceipt = {
-    version: '1.2.4',
+    version: '1.3',
     target: input.deliveryTarget ?? 'project-context',
     elapsedMs: Math.max(0, Date.now() - startedAt),
     budget: {

package/src/memory/long-term-store.ts

@@ -0,0 +1,242 @@
+import { randomUUID } from 'node:crypto';
+import { getDatabase } from '../store/sqlite-db.js';
+import type {
+  LongTermMemory,
+  LongTermMemoryEvidence,
+  LongTermMemoryEvent,
+} from './long-term-types.js';
+
+function optionalText(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+function arrayValue(value: unknown): string[] {
+  if (typeof value !== 'string' || !value) return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.filter((item): item is string => typeof item === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+function rowToMemory(row: any): LongTermMemory {
+  return {
+    id: row.id,
+    originProjectId: row.originProjectId,
+    ownerId: row.ownerId,
+    scope: row.scope,
+    kind: row.kind,
+    state: row.state,
+    portability: row.portability,
+    title: row.title,
+    content: row.content,
+    facts: arrayValue(row.factsJson),
+    tags: arrayValue(row.tagsJson),
+    ...(optionalText(row.applicability) ? { applicability: row.applicability } : {}),
+    origin: row.origin,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    ...(optionalText(row.qualifiedAt) ? { qualifiedAt: row.qualifiedAt } : {}),
+    ...(optionalText(row.approvedAt) ? { approvedAt: row.approvedAt } : {}),
+    ...(optionalText(row.archivedAt) ? { archivedAt: row.archivedAt } : {}),
+    ...(optionalText(row.supersededBy) ? { supersededBy: row.supersededBy } : {}),
+    ...(optionalText(row.lastValidatedAt) ? { lastValidatedAt: row.lastValidatedAt } : {}),
+    accessCount: Number(row.accessCount ?? 0),
+    ...(optionalText(row.lastAccessedAt) ? { lastAccessedAt: row.lastAccessedAt } : {}),
+  } as LongTermMemory;
+}
+
+function rowToEvidence(row: any): LongTermMemoryEvidence {
+  return {
+    id: row.id,
+    memoryId: row.memoryId,
+    kind: row.kind,
+    referenceId: row.referenceId,
+    relation: row.relation,
+    ...(optionalText(row.locator) ? { locator: row.locator } : {}),
+    ...(optionalText(row.capturedHash) ? { capturedHash: row.capturedHash } : {}),
+    createdAt: row.createdAt,
+  } as LongTermMemoryEvidence;
+}
+
+function rowToEvent(row: any): LongTermMemoryEvent {
+  return {
+    id: row.id,
+    memoryId: row.memoryId,
+    kind: row.kind,
+    ...(optionalText(row.fromState) ? { fromState: row.fromState } : {}),
+    ...(optionalText(row.toState) ? { toState: row.toState } : {}),
+    ...(optionalText(row.detail) ? { detail: row.detail } : {}),
+    createdAt: row.createdAt,
+  } as LongTermMemoryEvent;
+}
+
+/** Persistence only. Lifecycle, privacy, and portability policy live in long-term.ts. */
+export class LongTermMemoryStore {
+  private db: any = null;
+
+  async init(dataDir: string): Promise<void> {
+    this.db = getDatabase(dataDir);
+  }
+
+  transaction<T>(fn: () => T): T {
+    return this.db.transaction(fn)();
+  }
+
+  get(id: string): LongTermMemory | undefined {
+    const row = this.db.prepare('SELECT * FROM long_term_memories WHERE id = ?').get(id);
+    return row ? rowToMemory(row) : undefined;
+  }
+
+  list(options: { ownerId?: string; originProjectId?: string; limit?: number } = {}): LongTermMemory[] {
+    const limit = Math.max(1, Math.min(1_000, Math.floor(options.limit ?? 500)));
+    const clauses: string[] = [];
+    const params: unknown[] = [];
+    if (options.ownerId) {
+      clauses.push('ownerId = ?');
+      params.push(options.ownerId);
+    }
+    if (options.originProjectId) {
+      clauses.push('originProjectId = ?');
+      params.push(options.originProjectId);
+    }
+    const where = clauses.length ? ' WHERE ' + clauses.join(' AND ') : '';
+    const rows = this.db.prepare(
+      'SELECT * FROM long_term_memories' + where + ' ORDER BY updatedAt DESC, id LIMIT ?',
+    ).all(...params, limit);
+    return rows.map(rowToMemory);
+  }
+
+  insert(memory: LongTermMemory): void {
+    this.db.prepare(`
+      INSERT INTO long_term_memories (
+        id, originProjectId, ownerId, scope, kind, state, portability,
+        title, content, factsJson, tagsJson, applicability, origin,
+        createdAt, updatedAt, qualifiedAt, approvedAt, archivedAt,
+        supersededBy, lastValidatedAt, accessCount, lastAccessedAt
+      ) VALUES (
+        @id, @originProjectId, @ownerId, @scope, @kind, @state, @portability,
+        @title, @content, @factsJson, @tagsJson, @applicability, @origin,
+        @createdAt, @updatedAt, @qualifiedAt, @approvedAt, @archivedAt,
+        @supersededBy, @lastValidatedAt, @accessCount, @lastAccessedAt
+      )
+    `).run({
+      ...memory,
+      factsJson: JSON.stringify(memory.facts),
+      tagsJson: JSON.stringify(memory.tags),
+      applicability: memory.applicability ?? null,
+      qualifiedAt: memory.qualifiedAt ?? null,
+      approvedAt: memory.approvedAt ?? null,
+      archivedAt: memory.archivedAt ?? null,
+      supersededBy: memory.supersededBy ?? null,
+      lastValidatedAt: memory.lastValidatedAt ?? null,
+      lastAccessedAt: memory.lastAccessedAt ?? null,
+    });
+  }
+
+  update(memory: LongTermMemory): void {
+    this.db.prepare(`
+      UPDATE long_term_memories SET
+        scope = @scope,
+        kind = @kind,
+        state = @state,
+        portability = @portability,
+        title = @title,
+        content = @content,
+        factsJson = @factsJson,
+        tagsJson = @tagsJson,
+        applicability = @applicability,
+        updatedAt = @updatedAt,
+        qualifiedAt = @qualifiedAt,
+        approvedAt = @approvedAt,
+        archivedAt = @archivedAt,
+        supersededBy = @supersededBy,
+        lastValidatedAt = @lastValidatedAt,
+        accessCount = @accessCount,
+        lastAccessedAt = @lastAccessedAt
+      WHERE id = @id
+    `).run({
+      ...memory,
+      factsJson: JSON.stringify(memory.facts),
+      tagsJson: JSON.stringify(memory.tags),
+      applicability: memory.applicability ?? null,
+      qualifiedAt: memory.qualifiedAt ?? null,
+      approvedAt: memory.approvedAt ?? null,
+      archivedAt: memory.archivedAt ?? null,
+      supersededBy: memory.supersededBy ?? null,
+      lastValidatedAt: memory.lastValidatedAt ?? null,
+      lastAccessedAt: memory.lastAccessedAt ?? null,
+    });
+  }
+
+  insertEvidence(input: Omit<LongTermMemoryEvidence, 'id' | 'createdAt'> & { createdAt?: string }): LongTermMemoryEvidence {
+    const evidence: LongTermMemoryEvidence = {
+      id: randomUUID(),
+      ...input,
+      createdAt: input.createdAt ?? new Date().toISOString(),
+    };
+    this.db.prepare(`
+      INSERT INTO long_term_memory_evidence (
+        id, memoryId, kind, referenceId, relation, locator, capturedHash, createdAt
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      evidence.id,
+      evidence.memoryId,
+      evidence.kind,
+      evidence.referenceId,
+      evidence.relation,
+      evidence.locator ?? null,
+      evidence.capturedHash ?? null,
+      evidence.createdAt,
+    );
+    return evidence;
+  }
+
+  listEvidence(memoryId: string): LongTermMemoryEvidence[] {
+    return this.db.prepare(`
+      SELECT * FROM long_term_memory_evidence WHERE memoryId = ? ORDER BY createdAt ASC, id
+    `).all(memoryId).map(rowToEvidence);
+  }
+
+  recordEvent(input: Omit<LongTermMemoryEvent, 'id' | 'createdAt'> & { createdAt?: string }): LongTermMemoryEvent {
+    const event: LongTermMemoryEvent = {
+      id: randomUUID(),
+      ...input,
+      createdAt: input.createdAt ?? new Date().toISOString(),
+    };
+    this.db.prepare(`
+      INSERT INTO long_term_memory_events (id, memoryId, kind, fromState, toState, detail, createdAt)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      event.id,
+      event.memoryId,
+      event.kind,
+      event.fromState ?? null,
+      event.toState ?? null,
+      event.detail ?? null,
+      event.createdAt,
+    );
+    return event;
+  }
+
+  listEvents(memoryId: string): LongTermMemoryEvent[] {
+    return this.db.prepare(`
+      SELECT * FROM long_term_memory_events WHERE memoryId = ? ORDER BY createdAt ASC, rowid ASC
+    `).all(memoryId).map(rowToEvent);
+  }
+
+  markAccess(ids: string[], at = new Date().toISOString()): void {
+    const unique = [...new Set(ids.filter(Boolean))];
+    if (unique.length === 0) return;
+    const statement = this.db.prepare(`
+      UPDATE long_term_memories
+      SET accessCount = accessCount + 1, lastAccessedAt = ?
+      WHERE id = ?
+    `);
+    this.db.transaction(() => {
+      for (const id of unique) statement.run(at, id);
+    })();
+  }
+
+}

package/src/memory/long-term-types.ts

@@ -0,0 +1,136 @@
+/**
+ * Durable cognitive-memory contracts. These types are intentionally separate
+ * from Observation provenance and Knowledge Claim truth contracts.
+ */
+
+export const LONG_TERM_MEMORY_KINDS = ['episodic', 'semantic', 'procedural'] as const;
+export type LongTermMemoryKind = typeof LONG_TERM_MEMORY_KINDS[number];
+
+export const LONG_TERM_MEMORY_SCOPES = ['project', 'user', 'team'] as const;
+export type LongTermMemoryScope = typeof LONG_TERM_MEMORY_SCOPES[number];
+
+export const LONG_TERM_MEMORY_STATES = [
+  'candidate',
+  'qualified',
+  'approved',
+  'archived',
+  'superseded',
+] as const;
+export type LongTermMemoryState = typeof LONG_TERM_MEMORY_STATES[number];
+
+export const LONG_TERM_MEMORY_PORTABILITIES = ['project-bound', 'portable'] as const;
+export type LongTermMemoryPortability = typeof LONG_TERM_MEMORY_PORTABILITIES[number];
+
+export const LONG_TERM_MEMORY_EVIDENCE_KINDS = [
+  'observation',
+  'claim',
+  'workflow',
+  'session',
+  'checkpoint',
+  'git',
+  'code',
+  'test',
+  'run',
+  'document',
+  'manual',
+  'user',
+] as const;
+export type LongTermMemoryEvidenceKind = typeof LONG_TERM_MEMORY_EVIDENCE_KINDS[number];
+
+export const LONG_TERM_MEMORY_EVIDENCE_RELATIONS = [
+  'supports',
+  'verifies',
+  'derives',
+  'user-confirmed',
+] as const;
+export type LongTermMemoryEvidenceRelation = typeof LONG_TERM_MEMORY_EVIDENCE_RELATIONS[number];
+
+export type LongTermMemoryOrigin = 'manual' | 'agent' | 'hook' | 'git' | 'migration';
+
+export interface LongTermMemoryEvidence {
+  id: string;
+  memoryId: string;
+  kind: LongTermMemoryEvidenceKind;
+  referenceId: string;
+  relation: LongTermMemoryEvidenceRelation;
+  locator?: string;
+  capturedHash?: string;
+  createdAt: string;
+}
+
+export interface LongTermMemory {
+  id: string;
+  /** Project from which this item and its evidence originated. */
+  originProjectId: string;
+  /** Local stable owner identity. Team and project records retain attribution. */
+  ownerId: string;
+  scope: LongTermMemoryScope;
+  kind: LongTermMemoryKind;
+  state: LongTermMemoryState;
+  portability: LongTermMemoryPortability;
+  title: string;
+  content: string;
+  facts: string[];
+  tags: string[];
+  /** Short condition explaining when the procedure/fact applies. */
+  applicability?: string;
+  origin: LongTermMemoryOrigin;
+  createdAt: string;
+  updatedAt: string;
+  qualifiedAt?: string;
+  approvedAt?: string;
+  archivedAt?: string;
+  supersededBy?: string;
+  lastValidatedAt?: string;
+  accessCount: number;
+  lastAccessedAt?: string;
+}
+
+export type LongTermMemoryEventKind = 'created' | 'qualified' | 'approved' | 'archived' | 'superseded';
+
+export interface LongTermMemoryEvent {
+  id: string;
+  memoryId: string;
+  kind: LongTermMemoryEventKind;
+  fromState?: LongTermMemoryState;
+  toState?: LongTermMemoryState;
+  detail?: string;
+  createdAt: string;
+}
+
+export interface LongTermMemoryReader {
+  projectId: string;
+  ownerId?: string;
+  agentId?: string;
+  isTeamMember?: boolean;
+}
+
+export interface LongTermMemoryEvidenceInput {
+  kind: LongTermMemoryEvidenceKind;
+  referenceId: string;
+  relation: LongTermMemoryEvidenceRelation;
+  locator?: string;
+  capturedHash?: string;
+}
+
+export interface CreateLongTermMemoryInput {
+  originProjectId: string;
+  ownerId: string;
+  scope: LongTermMemoryScope;
+  kind: LongTermMemoryKind;
+  portability?: LongTermMemoryPortability;
+  title: string;
+  content: string;
+  facts?: string[];
+  tags?: string[];
+  applicability?: string;
+  origin?: LongTermMemoryOrigin;
+  evidence: LongTermMemoryEvidenceInput[];
+}
+
+export interface LongTermMemorySelection {
+  memory: LongTermMemory;
+  evidence: LongTermMemoryEvidence[];
+  score: number;
+  reason: string;
+}