omegon 0.6.0

package/extensions/openspec/types.ts

@@ -0,0 +1,98 @@
+/**
+ * openspec/types — Shared type definitions for the OpenSpec extension.
+ *
+ * OpenSpec is the specification layer that sits between design exploration
+ * and implementation. It defines what must be true (specs) before any code
+ * is written, making the development loop: spec → test → code → verify.
+ */
+
+// ─── Spec Format ─────────────────────────────────────────────────────────────
+
+/**
+ * A Given/When/Then scenario for a requirement.
+ *
+ * Format in spec.md files:
+ *   #### Scenario: <title>
+ *   Given <precondition>
+ *   When <action>
+ *   Then <expected outcome>
+ */
+export interface Scenario {
+	title: string;
+	given: string;
+	when: string;
+	then: string;
+	/** Optional additional then-clauses ("And ...") */
+	and?: string[];
+}
+
+/**
+ * A requirement within a spec domain.
+ *
+ * Format in spec.md files:
+ *   ### Requirement: <title>
+ *   <description>
+ *   #### Scenario: ...
+ */
+export interface Requirement {
+	title: string;
+	description: string;
+	scenarios: Scenario[];
+}
+
+/**
+ * A section in a spec file grouping requirements by change type.
+ */
+export interface SpecSection {
+	type: "added" | "modified" | "removed";
+	requirements: Requirement[];
+}
+
+/**
+ * A parsed spec file with domain name and sections.
+ */
+export interface SpecFile {
+	/** Domain name derived from file path (e.g., "auth/tokens") */
+	domain: string;
+	/** Absolute path to the spec.md file */
+	filePath: string;
+	sections: SpecSection[];
+}
+
+// ─── Change Lifecycle ────────────────────────────────────────────────────────
+
+/**
+ * Lifecycle stages of an OpenSpec change:
+ *
+ *   proposed → specified → planned → implementing → verifying → archived
+ *
+ * - proposed: proposal.md exists, no specs yet
+ * - specified: specs/ directory has scenario files
+ * - planned: tasks.md exists (ready for /cleave)
+ * - implementing: tasks partially done
+ * - verifying: all tasks done, awaiting /assess spec
+ * - archived: moved to openspec/archive/
+ */
+export type ChangeStage =
+	| "proposed"
+	| "specified"
+	| "planned"
+	| "implementing"
+	| "verifying"
+	| "archived";
+
+/**
+ * Full status of an OpenSpec change including computed lifecycle stage.
+ */
+export interface ChangeInfo {
+	name: string;
+	path: string;
+	stage: ChangeStage;
+	hasProposal: boolean;
+	hasDesign: boolean;
+	hasSpecs: boolean;
+	hasTasks: boolean;
+	totalTasks: number;
+	doneTasks: number;
+	specs: SpecFile[];
+}

package/extensions/project-memory/DESIGN-global-mind.md

@@ -0,0 +1,198 @@
+# Global Mind & Edges — Design
+
+## Architecture
+
+```
+Project A (.pi/memory/facts.db)     Project B (.pi/memory/facts.db)
+  └─ default mind (project facts)     └─ default mind (project facts)
+         │                                    │
+         ▼ new facts trigger                  ▼ new facts trigger
+    ┌──────────────────────────────────────────────┐
+    │  Global FactStore (~/.pi/memory/facts.db)    │
+    │                                              │
+    │  facts table  ── generalized knowledge       │
+    │  edges table  ── relationships between facts │
+    │  provenance   ── which project sourced what  │
+    └──────────────────────────────────────────────┘
+```
+
+### Two databases, one extraction chain
+
+- **Project DB** (`$CWD/.pi/memory/facts.db`): Scoped facts about this codebase.
+  Already exists.
+- **Global DB** (`~/.pi/memory/facts.db`): Cross-cutting knowledge + edges.
+  New. Lives at user home, shared across all projects.
+
+Both are SQLite with the same FactStore class. The global DB adds an `edges`
+table for relationships between facts.
+
+## Schema Extension — edges table
+
+```sql
+CREATE TABLE IF NOT EXISTS edges (
+  id                  TEXT PRIMARY KEY,
+  source_fact_id      TEXT NOT NULL,
+  target_fact_id      TEXT NOT NULL,
+  relation_type       TEXT NOT NULL,      -- 'relates_to', 'contradicts', 'depends_on', 'generalizes', 'instance_of'
+  description         TEXT NOT NULL,      -- LLM-generated edge label
+  confidence          REAL NOT NULL DEFAULT 1.0,
+  last_reinforced     TEXT NOT NULL,
+  reinforcement_count INTEGER NOT NULL DEFAULT 1,
+  decay_rate          REAL NOT NULL DEFAULT 0.049,
+  status              TEXT NOT NULL DEFAULT 'active',
+  created_at          TEXT NOT NULL,
+  created_session     TEXT,
+  source_mind         TEXT,               -- which project mind the source fact came from
+  target_mind         TEXT,               -- which project mind the target fact came from
+  FOREIGN KEY (source_fact_id) REFERENCES facts(id) ON DELETE CASCADE,
+  FOREIGN KEY (target_fact_id) REFERENCES facts(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_fact_id) WHERE status = 'active';
+CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_fact_id) WHERE status = 'active';
+CREATE INDEX IF NOT EXISTS idx_edges_type   ON edges(relation_type)  WHERE status = 'active';
+```
+
+Edges decay with the same math as facts. Reinforcement extends half-life.
+When a fact is archived/superseded, CASCADE deletes its edges.
+
+## Extraction Chain
+
+Single extraction event, two phases:
+
+### Phase 1: Project extraction (existing)
+```
+conversation context + project facts → JSONL actions → processExtraction(project_mind)
+                                                        returns { reinforced, added, newFactIds[] }
+```
+
+### Phase 2: Global extraction (new, conditional)
+Only fires if Phase 1 produced new facts (`newFactIds.length > 0`).
+
+```
+new project facts + global facts → JSONL actions → processExtraction(global_mind)
+                                                    + processEdges(global_mind)
+```
+
+The global extraction prompt is different:
+- Receives the newly-created project facts (with project context)
+- Receives existing global facts (with IDs)
+- Asks: "What generalizable knowledge do these new facts represent?
+         What connections exist between these facts and existing global knowledge?"
+- Outputs the same action types PLUS:
+  ```
+  {"type":"connect","source":"<fact_id>","target":"<fact_id>","relation":"relates_to","description":"Both involve..."}
+  ```
+
+### Cost control
+- Phase 2 only fires when new facts are created (not on pure reinforcements)
+- Phase 2 prompt is smaller: just new facts + global facts, no conversation replay
+- Global mind decay is slower (longer base half-life) — fewer facts churn through
+
+## processExtraction changes
+
+Current return: `{ reinforced: number, added: number }`
+New return: `{ reinforced: number, added: number, newFactIds: string[] }`
+
+This is the signal that chains Phase 1 → Phase 2.
+
+## ExtractionAction changes
+
+```typescript
+export interface ExtractionAction {
+  type: "observe" | "reinforce" | "supersede" | "archive" | "connect";
+  id?: string;
+  section?: SectionName;
+  content?: string;
+  // connect-specific:
+  source?: string;       // source fact ID
+  target?: string;       // target fact ID
+  relation?: string;     // relation_type
+  description?: string;  // edge label
+}
+```
+
+`connect` actions are only valid in global extraction. processExtraction
+ignores them; processEdges handles them.
+
+## Global extraction prompt
+
+```
+You are a cross-project knowledge synthesizer. You receive:
+1. New facts just extracted from a coding session (with project context)
+2. Existing facts in the global knowledge base (with IDs)
+
+Your job: identify generalizable knowledge and connections.
+
+ACTIONS:
+
+{"type":"observe","section":"Architecture","content":"..."}
+  → A new fact generalizes beyond its source project. Rewrite it to be project-agnostic.
+
+{"type":"reinforce","id":"abc123"}
+  → An existing global fact is confirmed by this project's new evidence.
+
+{"type":"connect","source":"<id>","target":"<id>","relation":"relates_to","description":"..."}
+  → Two facts are meaningfully related. Relation types:
+    - relates_to: general thematic connection
+    - contradicts: facts are in tension
+    - depends_on: source fact requires target fact
+    - generalizes: source is a more general form of target
+    - instance_of: source is a specific instance of target pattern
+
+RULES:
+- Only promote facts that would be useful across MULTIPLE projects.
+- Rewrite promoted facts to remove project-specific details.
+- Connections should represent genuine analytical insight, not surface similarity.
+- Prefer fewer, high-quality connections over many weak ones.
+- Output ONLY valid JSONL.
+```
+
+## Context injection
+
+When rendering memory for LLM context:
+1. Project facts (current behavior)
+2. Relevant global facts (FTS5 query using project context as search terms)
+3. Edges connecting injected facts (shows the agent relationships it should be aware of)
+
+This gives the agent both project-specific and cross-cutting context.
+
+## Rendering format
+
+```markdown
+## Global Knowledge
+
+- **Architecture**: Pattern X applies across distributed systems [↔ relates_to: "Local finding Y"]
+- **Decisions**: Embedded DBs preferred over client-server for CLI tooling [← generalizes: project-specific SQLite choice]
+```
+
+Edges rendered inline as annotations on the facts they connect.
+
+## Decay parameters — global mind
+
+Longer half-life baseline since global facts should be more durable:
+
+```typescript
+const GLOBAL_DECAY = {
+  baseRate: 0.033,          // ~21 day half-life (vs 14 for project)
+  reinforcementFactor: 2.0, // stronger reinforcement effect
+  minimumConfidence: 0.1,
+};
+```
+
+## File changes
+
+| File | Change |
+|------|--------|
+| `factstore.ts` | Add `edges` table to schema, `storeEdge()`, `getEdgesForFact()`, `processEdges()`. Return `newFactIds` from `processExtraction`. |
+| `extraction-v2.ts` | Add `buildGlobalExtractionPrompt()`, `formatNewFactsForGlobalExtraction()`. |
+| `index.ts` | Open global FactStore at `~/.pi/memory/facts.db`. Chain Phase 2 after Phase 1. Include global facts in context injection. |
+| `triggers.ts` | No changes — trigger logic is Phase 1 only. Phase 2 is conditional on Phase 1 output. |
+| `types.ts` | Add `globalMemoryDir` config option. |
+
+## Open questions
+
+1. **Edge rendering budget**: How many global facts + edges to inject alongside project facts? Need to avoid blowing context window.
+2. **Edge search**: Should `memory_search_archive` also search edges? FTS5 on edge descriptions?
+3. **Manual edge creation**: Should there be a `memory_connect` tool for explicit user-created edges?
+4. **Bidirectionality**: Are edges directional or bidirectional? Current design is directional (source → target) but `relates_to` is inherently bidirectional.

package/extensions/project-memory/README.md

@@ -0,0 +1,202 @@
+# Project Memory Extension
+
+Persistent, semantic memory for the pi coding agent. Facts, decisions, and patterns survive across sessions and inform future work.
+
+## Architecture
+
+```
+index.ts          — Extension entry: tools, lifecycle events, context injection
+factstore.ts      — SQLite-backed fact/episode/vector storage with FTS5
+embeddings.ts     — Ollama embedding client, cosine similarity, vector serialization
+extraction-v2.ts  — Subagent extraction (JSONL actions), episode generation
+triggers.ts       — Extraction trigger heuristics (token count, tool calls)
+template.ts       — Section definitions (Architecture, Decisions, etc.)
+types.ts          — Shared types and default config
+migration.ts      — One-time markdown → SQLite migration
+```
+
+### Data Model
+
+**Facts** are atomic knowledge units stored in SQLite with:
+- Section classification (Architecture, Decisions, Constraints, Known Issues, Patterns & Conventions, Specs)
+- Confidence decay based on age and reinforcement count
+- Content-hash deduplication
+- Supersession chains for fact evolution
+- FTS5 full-text search index
+
+**Minds** are named memory stores. Each project gets a `default` mind. Additional minds can be created for branches, experiments, or ingested external knowledge.
+
+**Episodes** are session narratives generated at shutdown — capturing what happened, what was decided, and what's still open. Linked to the facts created during that session.
+
+**Edges** connect facts with typed relationships (depends_on, contradicts, enables, etc.) forming a knowledge graph.
+
+**Vectors** (Float32Array BLOBs) enable semantic retrieval via cosine similarity against Ollama-generated embeddings.
+
+### Schema Versioning
+
+The database uses incremental schema versioning via a `schema_version` table:
+
+| Version | Description |
+|---------|-------------|
+| 1       | Core tables: minds, facts, facts_fts, edges |
+| 2       | Vector + episode tables: facts_vec, episodes, episode_facts, episodes_vec |
+
+Migrations run automatically on database open. `CREATE TABLE IF NOT EXISTS` ensures idempotency.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_query` | Read all project memory (full dump) |
+| `memory_recall(query)` | Semantic search — returns ranked facts by relevance × confidence |
+| `memory_store(section, content)` | Store a new fact with pre-store conflict detection |
+| `memory_supersede(fact_id, section, content)` | Atomically replace a fact |
+| `memory_archive(fact_ids)` | Archive stale facts |
+| `memory_search_archive(query)` | Search archived/superseded facts |
+| `memory_connect(source, target, relation)` | Create a typed edge between facts |
+| `memory_compact` | Trigger context compaction with extraction |
+| `memory_recall(query)` | Semantic search over facts |
+| `memory_episodes(query)` | Search session episode narratives |
+| `memory_focus(fact_ids)` | Pin facts to working memory (survives compaction) |
+| `memory_release` | Clear working memory buffer |
+
+## Semantic Features (v3 — Hippocampus)
+
+Requires a local Ollama instance with an embedding model:
+
+```bash
+ollama pull qwen3-embedding:0.6b   # 639MB, 1024 dims, ~108ms/embed
+# or
+ollama pull qwen3-embedding:4b     # 2.5GB, 2048 dims, higher quality
+```
+
+### How It Works
+
+1. **Background indexing**: On session start, all unembedded facts are vectorized asynchronously
+2. **Contextual injection**: `before_agent_start` embeds the user prompt and injects only the most relevant facts (top-20 semantic + core sections + working memory) instead of dumping all facts
+3. **Semantic recall**: `memory_recall(query)` returns facts ranked by cosine similarity × confidence
+4. **Conflict detection**: `memory_store` checks for >85% similar facts BEFORE storing and warns about potential duplicates
+5. **Episode search**: `memory_episodes(query)` finds relevant past session narratives
+6. **Working memory**: Facts accessed via recall/store enter a session-scoped buffer (cap 25) with priority injection
+
+### Graceful Degradation
+
+All semantic features fall back when Ollama is unavailable:
+- `memory_recall` → FTS5 keyword search
+- Context injection → full fact dump
+- Conflict detection → skipped
+- Episode search → most recent episodes (chronological)
+- Status bar shows `🧠⚡` when embeddings available, `🧠` when not
+
+### Dimension Mismatch Handling
+
+If the embedding model changes between sessions (e.g., switching from 0.6b to 4b), vectors with the old dimensions are automatically purged and re-indexed. The `purgeStaleVectors()` method removes vectors whose `dims` column doesn't match the current model's output. Semantic search also skips individual vectors with mismatched dimensions as a safety net.
+
+## Context Injection
+
+On each agent turn, memory is injected as a system message. The injection strategy depends on available capabilities:
+
+| Condition | Strategy |
+|-----------|----------|
+| <3 facts | Welcome message only |
+| No embeddings OR <50% vector coverage OR <20 facts | Full dump via `renderForInjection()` |
+| Embeddings available + sufficient coverage | Semantic subset: core sections (Constraints, Specs) + working memory + top-20 relevant facts |
+
+Recent episodes (last 3) and global knowledge are always appended when available.
+
+## Extraction
+
+A background subagent periodically scans conversation history and emits JSONL actions:
+
+```jsonl
+{"type":"observe","section":"Architecture","content":"System uses k8s 1.29"}
+{"type":"reinforce","id":"abc123"}
+{"type":"supersede","id":"def456","section":"Architecture","content":"Updated to k8s 1.30"}
+{"type":"archive","id":"ghi789"}
+{"type":"connect","source":"abc123","target":"def456","relation":"replaces"}
+```
+
+Extraction triggers when:
+- Token count exceeds threshold since last extraction
+- Sufficient tool calls have occurred
+- Manual `/memory refresh` command
+- Session compaction event
+
+### Episode Generation
+
+At session shutdown (if >5 messages exchanged), a subagent generates a session episode:
+
+```json
+{"title":"Migrated auth from JWT to OIDC","narrative":"Goal was to replace JWT auth with OIDC. Updated middleware, added Keycloak config, fixed 3 test failures. Decision: use PKCE flow for all clients. Open: need to update API docs."}
+```
+
+Episodes are stored with links to facts created during the session and optionally embedded for semantic search.
+
+## Configuration
+
+Defined in `types.ts` as `MemoryConfig`:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `extractionModel` | `gpt-5.3-codex-spark` | Cheap GPT model for extraction subagent |
+| `embeddingProvider` | `openai` | Embedding backend for semantic retrieval |
+| `embeddingModel` | `text-embedding-3-small` | Cheap cloud embedding model |
+| `maxLines` | 50 | Max facts before pruning |
+| `minimumTokensToInit` | 10000 | Min tokens before first extraction |
+| `minimumTokensBetweenUpdate` | 5000 | Min tokens between extractions |
+| `toolCallsBetweenUpdates` | 8 | Min tool calls between extractions |
+| `extractionTimeout` | 60000 | Extraction subprocess timeout (ms) |
+| `shutdownExtractionTimeout` | 15000 | Episode generation timeout (ms) |
+
+## Confidence Decay
+
+Facts decay exponentially based on time since last reinforcement:
+
+```
+confidence = e^(-ln(2) × daysSince / halfLife)
+halfLife = baseHalfLife × reinforcementFactor^(count - 1)
+```
+
+| Profile | Base Half-Life | Reinforcement Factor |
+|---------|---------------|---------------------|
+| Project | 14 days | 1.8× per reinforcement |
+| Global | 30 days | 2.5× per reinforcement |
+
+**Specs section facts are exempt from decay** (always confidence 1.0).
+
+## Testing
+
+```bash
+cd extensions/project-memory
+npx tsx --test *.test.ts
+```
+
+Test files:
+- `factstore.test.ts` — Core CRUD, dedup, supersession, archival, FTS5, rendering, minds, extraction processing, decay math
+- `embeddings.test.ts` — Cosine similarity, vector serialization roundtrips, dimension constants
+- `vectors-episodes.test.ts` — Vector storage, semantic search, dimension mismatch handling, conflict detection, episode CRUD, episode vectors, renderFactList, JSONL export/import with episodes, schema versioning
+- `edges.test.ts` — Edge CRUD, dedup, rendering, cross-mind edges, extraction processing
+- `extraction.test.ts` — Trigger heuristics
+- `template.test.ts` — Section definitions, markdown template, appendToSection
+- `migration.test.ts` — Markdown → SQLite migration
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/memory` | Show stats: fact count, confidence, vector coverage, episodes, working memory |
+| `/memory refresh` | Force extraction cycle (prune, consolidate, reinforce) |
+| `/memory export` | Export facts.jsonl for cross-machine sync |
+
+## File Layout
+
+```
+.pi/memory/
+├── facts.db           # SQLite database (gitignored)
+├── facts.db-wal       # WAL journal (gitignored)
+├── facts.jsonl        # Portable export (git-tracked)
+└── memory.md.migrated # Pre-migration backup (if migrated)
+
+~/.pi/memory/
+└── global.db          # Cross-project global knowledge
+```