omegon 0.6.0

package/extensions/project-memory/api-types.ts

@@ -0,0 +1,382 @@
+/**
+ * project-memory/api-types — Omega /api/memory/* HTTP contract
+ *
+ * This file is the source of truth for the wire protocol between:
+ *   - The TypeScript auspex bridge (TS extension, pi API surface)
+ *   - The Rust Omega daemon (/api/memory/* Axum routes)
+ *
+ * Field names are snake_case throughout to match Rust serde conventions
+ * (#[serde(rename_all = "snake_case")] or #[serde(deny_unknown_fields)]).
+ *
+ * When the Rust implementation is built, each interface here becomes a
+ * corresponding Rust struct deriving Serialize, Deserialize, with field
+ * names identical to these. Any deviation is a bug in the Rust port.
+ *
+ * Versioning: the HTTP API is versioned via the Accept header or a /v1/ prefix.
+ * Breaking changes increment the major version. Additive fields use Option<T>
+ * with serde defaults in Rust and optional typing here.
+ */
+
+import type { SectionName } from "./template.ts";
+import type { DecayProfileName } from "./core.ts";
+
+// ─── Core record types ────────────────────────────────────────────────────────
+
+/**
+ * A memory fact as returned by the API.
+ * Mirrors the `facts` SQLite table — all fields except `embedding` (DB-only).
+ *
+ * Rust: src/memory/types.rs::Fact
+ */
+export interface FactRecord {
+  id: string;
+  mind: string;
+  content: string;
+  section: SectionName;
+  status: FactStatus;
+  confidence: number;
+  reinforcement_count: number;
+  decay_rate: number;
+  /** Discriminant for the decay profile used at write time. Persisted in DB.
+   *  Allows correct confidence computation at read time. Default: "standard". */
+  decay_profile: DecayProfileName;
+  last_reinforced: string;   // ISO 8601
+  created_at: string;        // ISO 8601
+  /** Lamport logical timestamp. Incremented on every mutation.
+   *  On git-sync conflict: higher version always wins. Default on import: 0. */
+  version: number;
+  superseded_by?: string;    // fact ID; present only when status === "superseded"
+  source?: string;           // origin annotation: "lifecycle:openspec:X" | "extraction" | "manual"
+}
+
+export type FactStatus = "active" | "archived" | "superseded";
+
+/**
+ * A session episode narrative.
+ * Rust: src/memory/types.rs::Episode
+ */
+export interface EpisodeRecord {
+  id: string;
+  mind: string;
+  date: string;        // ISO 8601 date
+  title: string;
+  narrative: string;   // free-form prose summary
+  created_at: string;  // ISO 8601
+  /** Design node IDs touched this session. Optional; populated by extraction subagent. */
+  affected_nodes?: string[];
+  /** OpenSpec change names touched this session. */
+  affected_changes?: string[];
+  /** git diff --stat summary of files changed. */
+  files_changed?: string[];
+  /** Semantic tags: "architecture", "bugfix", "refactor", "investigation", etc. */
+  tags?: string[];
+  /** Rough activity measure — number of LLM tool calls in this session. */
+  tool_calls_count?: number;
+}
+
+/**
+ * A directional relationship between two facts.
+ * Rust: src/memory/types.rs::Edge
+ */
+export interface EdgeRecord {
+  id: string;
+  source_id: string;
+  target_id: string;
+  relation: string;      // "depends_on", "contradicts", "generalizes", etc.
+  description?: string;
+  weight: number;        // 0.0–1.0; higher = stronger relationship
+  created_at: string;    // ISO 8601
+}
+
+// ─── POST /api/memory/facts ───────────────────────────────────────────────────
+
+export interface StoreFactRequest {
+  mind: string;
+  content: string;
+  section: SectionName;
+  /** Decay profile to use for this fact. Defaults to "standard". */
+  decay_profile?: DecayProfileName;
+  /** Optional initial confidence override (0.0–1.0). Default: 1.0. */
+  confidence?: number;
+  /** Origin annotation for provenance tracking. */
+  source?: string;
+}
+
+export interface StoreFactResponse {
+  /** The ID of the stored or matched fact. */
+  id: string;
+  /** What happened: new fact stored, existing fact reinforced, or exact duplicate found. */
+  action: "stored" | "reinforced" | "deduplicated";
+  fact: FactRecord;
+}
+
+// ─── GET /api/memory/context ──────────────────────────────────────────────────
+
+export interface ContextRequest {
+  mind: string;
+  /** Raw text query used for semantic fact selection. Omega embeds it.
+   *  Required when mode === "semantic". */
+  query?: string;
+  mode: InjectionMode;
+  /** Pinned fact IDs — always included first, before semantic or bulk selection. */
+  working_memory?: string[];
+  /** Maximum character budget for the rendered context block. Default: 12000.
+   *  Omega stops adding facts when the budget would be exceeded. */
+  max_chars?: number;
+  /** Per-section maximum fact counts. Overrides Omega's default caps. */
+  section_caps?: Partial<Record<SectionName, number>>;
+  /** Number of recent session episodes to include. Default: 1. 0 to suppress. */
+  episodes?: number;
+  /** Whether to include global knowledge (cross-project facts).
+   *  In semantic mode: included only if relevant (similarity ≥ 0.45).
+   *  In bulk mode: excluded unless explicitly true. Default: false. */
+  include_global?: boolean;
+}
+
+export type InjectionMode = "semantic" | "bulk";
+
+export interface ContextResponse {
+  /** Pre-rendered markdown block suitable for direct LLM context injection. */
+  markdown: string;
+  stats: ContextStats;
+}
+
+export interface ContextStats {
+  facts_injected: number;
+  mode: InjectionMode;
+  episodes_injected: number;
+  global_facts_injected: number;
+  char_count: number;
+  /** True if some facts were dropped to stay within max_chars budget. */
+  budget_exhausted: boolean;
+}
+
+// ─── POST /api/memory/recall ──────────────────────────────────────────────────
+
+export interface RecallRequest {
+  mind: string;
+  /** Raw text query. Omega embeds it and runs cosine similarity × decay scoring. */
+  query: string;
+  /** Number of results. Default: 10. */
+  k?: number;
+  /** Minimum cosine similarity. Default: 0.3. */
+  min_similarity?: number;
+  /** Optional section filter. */
+  section?: SectionName;
+}
+
+export interface RecallResponse {
+  facts: ScoredFact[];
+}
+
+export interface ScoredFact extends FactRecord {
+  /** Raw cosine similarity between query vector and fact vector (0.0–1.0). */
+  similarity: number;
+  /** Combined score: similarity × decay-adjusted confidence. Used for ranking. */
+  score: number;
+}
+
+// ─── GET /api/memory/facts ────────────────────────────────────────────────────
+
+export interface ListFactsRequest {
+  mind: string;
+  section?: SectionName;
+  status?: FactStatus;
+}
+
+export interface ListFactsResponse {
+  facts: FactRecord[];
+  total: number;
+}
+
+// ─── PATCH /api/memory/facts/:id ─────────────────────────────────────────────
+
+export interface UpdateFactRequest {
+  action: UpdateFactAction;
+  /** For "supersede": the replacement fact content. */
+  content?: string;
+  /** For "supersede": the section for the replacement fact.
+   *  Defaults to the original fact's section. */
+  section?: SectionName;
+  /** For "supersede": the decay profile for the replacement fact.
+   *  Defaults to the original fact's decay profile. */
+  decay_profile?: DecayProfileName;
+}
+
+export type UpdateFactAction = "reinforce" | "archive" | "supersede";
+
+export interface UpdateFactResponse {
+  action: UpdateFactAction;
+  fact: FactRecord;
+  /** Present when action === "supersede". The new replacement fact. */
+  new_fact?: FactRecord;
+}
+
+// ─── POST /api/memory/edges ───────────────────────────────────────────────────
+
+export interface CreateEdgeRequest {
+  source_id: string;
+  target_id: string;
+  /** Short verb phrase: "depends_on", "contradicts", "enables", "generalizes", etc. */
+  relation: string;
+  description?: string;
+}
+
+export interface CreateEdgeResponse {
+  edge: EdgeRecord;
+  /** True if an existing edge was reinforced (weight increased) rather than created. */
+  reinforced: boolean;
+}
+
+// ─── GET /api/memory/export ───────────────────────────────────────────────────
+
+/**
+ * Response: Content-Type: application/x-ndjson
+ * Each line is one JSONL record: FactRecord | EpisodeRecord | EdgeRecord | MindRecord
+ * Line ordering: minds first, then facts, then edges, then episodes.
+ * Deterministic output (sorted by id within each type) for stable git diffs.
+ */
+export interface ExportOptions {
+  mind: string;
+  /** Include archived and superseded facts. Default: true (full history). */
+  include_archived?: boolean;
+}
+
+// ─── POST /api/memory/import ─────────────────────────────────────────────────
+
+export interface ImportRequest {
+  /** Raw JSONL content. Each line is a fact, episode, edge, or mind record.
+   *  Conflict resolution: higher `version` (Lamport timestamp) always wins.
+   *  Facts without `version` field get version=0 on import. */
+  jsonl: string;
+}
+
+export interface ImportResponse {
+  imported: number;    // new records
+  reinforced: number;  // existing records with lower version updated
+  skipped: number;     // same or lower version, no change
+  errors: number;      // lines that failed to parse
+}
+
+// ─── POST /api/memory/episodes ───────────────────────────────────────────────
+
+export interface StoreEpisodeRequest {
+  mind: string;
+  title: string;
+  narrative: string;
+  /** ISO 8601 date. Default: today. */
+  date?: string;
+  affected_nodes?: string[];
+  affected_changes?: string[];
+  files_changed?: string[];
+  tags?: string[];
+  tool_calls_count?: number;
+}
+
+export interface StoreEpisodeResponse {
+  episode: EpisodeRecord;
+}
+
+// ─── GET /api/memory/episodes ────────────────────────────────────────────────
+
+export interface ListEpisodesRequest {
+  mind: string;
+  /** Number of most recent episodes to return. Default: 3. */
+  k?: number;
+  /** Optional semantic query — returns episodes ranked by narrative similarity. */
+  query?: string;
+}
+
+export interface ListEpisodesResponse {
+  episodes: EpisodeRecord[];
+}
+
+// ─── POST /api/memory/parse-extraction ───────────────────────────────────────
+
+/**
+ * Validate and parse raw extraction subagent output.
+ * The TS extraction subagent sends LLM-generated JSONL here for typed validation.
+ * Omega parses each line against the ExtractionAction schema and returns
+ * validated actions + a list of lines that failed parsing.
+ *
+ * Rust: src/memory/extraction.rs::parse_extraction_output
+ */
+export interface ParseExtractionRequest {
+  /** Raw JSONL output from the extraction subagent. */
+  raw_output: string;
+}
+
+export interface ParseExtractionResponse {
+  actions: ExtractionAction[];
+  /** Lines that failed schema validation — for debugging. */
+  errors: string[];
+}
+
+export type ExtractionAction =
+  | { type: "store"; content: string; section: SectionName; decay_profile?: DecayProfileName }
+  | { type: "archive"; id: string }
+  | { type: "supersede"; id: string; content: string; section?: SectionName }
+  | { type: "connect"; source_id: string; target_id: string; relation: string; description?: string };
+
+// ─── GET /api/memory/stats ────────────────────────────────────────────────────
+
+export interface MemoryStatsResponse {
+  mind: string;
+  total_facts: number;
+  active_facts: number;
+  archived_facts: number;
+  superseded_facts: number;
+  facts_with_vectors: number;
+  embedding_model?: string;   // null if no vectors exist
+  embedding_dims?: number;
+  episodes: number;
+  edges: number;
+  db_size_bytes: number;
+  /** Lamport clock high-water mark — max version seen in this DB. */
+  version_hwm: number;
+}
+
+// ─── JSONL wire format ────────────────────────────────────────────────────────
+
+/**
+ * The canonical JSONL line types for git-sync.
+ * Each line is one of these discriminated union members.
+ * Rust: src/memory/jsonl.rs — use serde(tag = "type") for tagged deserialization.
+ */
+export type JsonlRecord =
+  | ({ type: "fact" } & FactRecord)
+  | ({ type: "episode" } & EpisodeRecord)
+  | ({ type: "edge" } & EdgeRecord)
+  | ({ type: "mind" } & MindRecord);
+
+export interface MindRecord {
+  name: string;
+  created_at: string;
+  description?: string;
+}
+
+// ─── Embedding metadata ───────────────────────────────────────────────────────
+
+/**
+ * Embedding model registration.
+ * Stored in `embedding_metadata` table — one row per model ever used.
+ * Facts in `facts_vec` carry a `model_name` FK to this table.
+ *
+ * Mismatch between query vector dims and stored model dims is a hard error:
+ * EmbeddingDimensionMismatch { expected: u32, got: u32, model: String }
+ *
+ * Rust: src/memory/vectors.rs::EmbeddingMetadata
+ */
+export interface EmbeddingMetadata {
+  model_name: string;   // e.g., "qwen3-embedding:0.6b"
+  dims: number;         // e.g., 384
+  inserted_at: string;  // ISO 8601 — when first used
+}
+
+export interface EmbeddingDimensionMismatchError {
+  error: "EmbeddingDimensionMismatch";
+  expected_dims: number;
+  got_dims: number;
+  stored_model: string;
+  message: string;
+}

package/extensions/project-memory/compaction-policy.ts

@@ -0,0 +1,29 @@
+/**
+ * Pure helpers for compaction policy and prompt hygiene.
+ */
+
+import type { MemoryConfig } from "./types.ts";
+
+/**
+ * Redact transient clipboard image temp paths captured from pi's clipboard paste flow.
+ * These files live under macOS temp directories and become stale/noisy immediately.
+ */
+export function sanitizeCompactionText(input: string): string {
+  return input.replace(
+    /\/var\/folders\/[A-Za-z0-9_-]+\/[A-Za-z0-9_-]+\/T\/pi-clipboard-[A-Fa-f0-9-]+\.(?:png|jpe?g|gif|webp)/g,
+    "[clipboard image attachment]",
+  );
+}
+
+/**
+ * Whether project-memory should intercept compaction before pi core.
+ * Local interception is only enabled for explicit local policy or fallback retry.
+ */
+export function shouldInterceptCompaction(
+  effortCompaction: "local" | "retribution" | "victory" | "gloriana" | undefined,
+  config: MemoryConfig,
+  useLocalCompaction: boolean,
+): boolean {
+  const liveCompactionLocal = effortCompaction ? effortCompaction === "local" : config.compactionLocalFirst;
+  return (liveCompactionLocal || useLocalCompaction) && config.compactionLocalFallback;
+}

package/extensions/project-memory/core.ts

@@ -0,0 +1,164 @@
+/**
+ * project-memory/core — Pure computation functions
+ *
+ * Zero dependencies: no DB, no pi API, no Node.js built-ins except crypto
+ * (available in all JS environments). This module is the direct Rust port target.
+ *
+ * Rust equivalents:
+ *   computeConfidence → src/memory/decay.rs::compute_confidence
+ *   cosineSimilarity  → src/memory/vectors.rs::cosine_similarity
+ *   vectorToBlob      → src/memory/vectors.rs::vector_to_blob
+ *   blobToVector      → src/memory/vectors.rs::blob_to_vector
+ *   contentHash       → src/memory/store.rs::content_hash
+ *   normalizeForHash  → src/memory/store.rs::normalize_for_hash
+ *
+ * Any behavioural change here must be reflected in the Rust implementation
+ * and verified by cross-impl tests (same inputs → same outputs).
+ */
+
+import * as crypto from "node:crypto";
+
+// ─── Decay profiles ──────────────────────────────────────────────────────────
+
+/** Project-level decay. Base half-life 14d; each reinforcement extends by 1.8×. */
+export const DECAY = {
+  baseRate: 0.05,           // ≈ ln(2)/14 — single unreinforced fact fades in ~2 weeks
+  reinforcementFactor: 1.8,
+  minimumConfidence: 0.1,
+  halfLifeDays: 14,
+} as const;
+
+/** Global-level decay. Shorter base (30d); cross-project reinforcement dramatically extends. */
+export const GLOBAL_DECAY = {
+  baseRate: Math.LN2 / 30,
+  reinforcementFactor: 2.5,
+  minimumConfidence: 0.1,
+  halfLifeDays: 30,
+} as const;
+
+/**
+ * Recent Work decay — ephemeral session breadcrumbs.
+ * halfLifeDays=2: written Monday, gone by Wednesday at ~50%.
+ * reinforcementFactor=1.0: reinforcement does NOT extend half-life.
+ */
+export const RECENT_WORK_DECAY = {
+  baseRate: Math.LN2 / 2,
+  reinforcementFactor: 1.0,
+  minimumConfidence: 0.01,
+  halfLifeDays: 2,
+} as const;
+
+export type DecayProfile = typeof DECAY | typeof GLOBAL_DECAY | typeof RECENT_WORK_DECAY;
+
+/** Stored profile discriminant — persisted in the `decay_profile` DB column. */
+export type DecayProfileName = "standard" | "global" | "recent_work";
+
+/** Map DB column value → DecayProfile object. Exhaustive — all names must be handled. */
+export function resolveDecayProfile(name: DecayProfileName): DecayProfile {
+  switch (name) {
+    case "standard":    return DECAY;
+    case "global":      return GLOBAL_DECAY;
+    case "recent_work": return RECENT_WORK_DECAY;
+  }
+}
+
+/**
+ * Maximum effective half-life regardless of reinforcement count.
+ * Prevents immortal facts — even highly reinforced facts decay eventually.
+ * Facts needing longer survival must be pinned via memory_focus.
+ */
+const MAX_HALF_LIFE_DAYS = 90;
+
+/**
+ * Compute current confidence for a fact based on time since last reinforcement.
+ *
+ * halfLife = profile.halfLifeDays × (profile.reinforcementFactor ^ (reinforcement_count - 1))
+ * halfLife = clamp(halfLife, 0, MAX_HALF_LIFE_DAYS)
+ * confidence = e^(−ln(2) × daysSinceReinforced / halfLife)
+ *
+ * Rust port: src/memory/decay.rs::compute_confidence
+ * Must produce bit-compatible results for the same float inputs.
+ */
+export function computeConfidence(
+  daysSinceReinforced: number,
+  reinforcementCount: number,
+  profile: DecayProfile = DECAY,
+): number {
+  const rawHalfLife = profile.halfLifeDays * Math.pow(profile.reinforcementFactor, reinforcementCount - 1);
+  const halfLife = Math.min(rawHalfLife, MAX_HALF_LIFE_DAYS);
+  const confidence = Math.exp(-Math.LN2 * daysSinceReinforced / halfLife);
+  return Math.max(confidence, 0);
+}
+
+// ─── Vector math ─────────────────────────────────────────────────────────────
+
+/**
+ * Cosine similarity between two Float32Arrays.
+ * Returns 0 if either vector has zero norm or dimensions differ.
+ *
+ * Rust port: src/memory/vectors.rs::cosine_similarity
+ * LLVM auto-vectorizes the inner loop on x86 (SSE/AVX) and ARM (NEON).
+ */
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  if (a.length !== b.length) return 0;
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot   += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+/**
+ * Serialize Float32Array to Buffer for SQLite BLOB storage.
+ * Layout: raw IEEE 754 little-endian f32 array (matches Rust's [f32] memory layout).
+ *
+ * Rust port: src/memory/vectors.rs — use bytemuck::cast_slice or std::mem::transmute.
+ */
+export function vectorToBlob(vec: Float32Array): Buffer {
+  return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+
+/**
+ * Deserialize Buffer from SQLite BLOB to Float32Array.
+ * Allocates a fresh aligned ArrayBuffer — safe regardless of Buffer alignment.
+ *
+ * Rust port: src/memory/vectors.rs — bytemuck::cast_slice::<u8, f32>.
+ */
+export function blobToVector(blob: Buffer): Float32Array {
+  const aligned = new ArrayBuffer(blob.length);
+  const view = new Uint8Array(aligned);
+  view.set(blob);
+  return new Float32Array(aligned);
+}
+
+// ─── Content hashing ─────────────────────────────────────────────────────────
+
+/**
+ * Normalize content for dedup hashing.
+ * Strips leading bullet dash, trims whitespace, lowercases, collapses runs of spaces.
+ *
+ * Rust port: src/memory/store.rs::normalize_for_hash
+ */
+export function normalizeForHash(content: string): string {
+  return content
+    .replace(/^-\s*/, "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, " ");
+}
+
+/**
+ * Compute a 16-hex-char content hash for deduplication.
+ * Uses sha256 truncated to 64 bits — collision probability negligible at expected fact counts.
+ *
+ * Rust port: src/memory/store.rs::content_hash — sha2::Sha256, hex encode, truncate to 16.
+ */
+export function contentHash(content: string): string {
+  return crypto.createHash("sha256")
+    .update(normalizeForHash(content))
+    .digest("hex")
+    .slice(0, 16);
+}