@tekmidian/pai 0.9.9 → 0.9.11

package/ARCHITECTURE.md

@@ -1,4 +1,4 @@
-# PAI Knowledge OS — Architecture (v0.8.0)
+# PAI Knowledge OS — Architecture (v0.9.10)
 
 Technical reference for PAI's architecture, database schema, CLI commands, and development setup.
 
@@ -1047,6 +1047,78 @@ These tables are populated by the PostToolUse hook classifier and queried by the
 
 **Indexes:** B-tree on project_id, session_id, type, created_at DESC, content_hash.
 
+### Knowledge Graph Entity Tables (PostgreSQL)
+
+Introduced in v0.9.10 to support entity deduplication and graph-completion search.
+
+**`kg_entities`** — Deduplicated named entities with content-address hashing:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | SERIAL | Primary key |
+| `project_id` | INTEGER | Owning project (FK → registry projects) |
+| `name` | TEXT | Canonical entity name (normalized) |
+| `type` | TEXT | Entity type: `person`, `project`, `library`, `concept`, `place`, `other` |
+| `content_hash` | TEXT | SHA-256 of `lower(trim(name))` — identity key for deduplication |
+| `last_accessed_at` | TIMESTAMPTZ | Timestamp of last `memory_get` that touched this entity |
+| `created_at` | TIMESTAMPTZ | First observation timestamp |
+
+The `content_hash` column carries a unique constraint per `project_id`. When two indexing passes encounter the same entity name, they resolve to the same row — no duplicates accumulate.
+
+**`kg_entity_chunks`** — Join table linking entities to the chunks they appear in:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `entity_id` | INTEGER | FK → kg_entities.id |
+| `chunk_id` | TEXT | FK → pai_chunks.id (SHA-256) |
+
+**Indexes:** Unique on `(project_id, content_hash)`, B-tree on entity_id, chunk_id.
+
+---
+
+### Graph-Completion Search Pipeline
+
+`graphCompletionSearch` in `src/memory/graph-search.ts` implements the four-stage pipeline:
+
+1. **Vector seeds** — calls the standard `memory_search` with `mode: "semantic"` to retrieve top-K chunks by embedding similarity.
+2. **Entity resolution** — for each seed chunk, looks up associated entities via `kg_entity_chunks`.
+3. **Graph traversal** — fetches one-hop neighbors from `kg_triples` for each resolved entity; collects their associated chunk IDs via `kg_entity_chunks`.
+4. **Re-rank** — merges seed chunks with neighbor-expanded candidates, deduplicates, and scores the full set with the cross-encoder. Returns results sorted by final cross-encoder score.
+
+The pipeline is invoked when the `memory_search` MCP tool receives `mode: "graph"`. It falls back to hybrid search in SQLite mode (no graph available).
+
+---
+
+### Feedback Weight EMA System
+
+`src/memory/feedback.ts` maintains a `search_feedback` table:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `chunk_id` | TEXT | FK → pai_chunks.id |
+| `project_id` | INTEGER | Owning project |
+| `weight` | REAL | Current EMA weight (default 1.0) |
+| `signal_count` | INTEGER | Total positive signals received |
+| `updated_at` | TIMESTAMPTZ | Last signal timestamp |
+
+When `memory_get` is called for a chunk, a positive signal is recorded and the weight updated:
+
+```
+new_weight = alpha * 1.0 + (1 - alpha) * old_weight   (alpha = 0.1 by default)
+```
+
+The `memory_search` result scorer multiplies each chunk's base score by its feedback weight before final ranking. A chunk accessed 10 times reaches approximately 1.65x its baseline score; one accessed 50 times approaches 2.0x.
+
+Access timestamps are written to both `kg_entities.last_accessed_at` (for entity rows) and `pai_chunks.last_accessed_at` (for chunk rows) on every `memory_get` call. This supports the recency boost calculation and enables future LRU eviction for very large knowledge bases.
+
+---
+
+### Multi-Tenant Isolation
+
+Every memory table (`pai_chunks`, `pai_files`, `kg_entities`, `kg_entity_chunks`, `kg_triples`, `pai_observations`, `pai_session_summaries`, `search_feedback`) carries a `project_id` column. All queries in the storage backend append `WHERE project_id = $1` when `all_projects` is false (the default).
+
+Cross-project visibility is opt-in: pass `all_projects: true` to `memory_search`, or use `--all` with the CLI. The `memory_tunnels` MCP tool explicitly queries across projects to surface cross-project concept bridges — this is its intended purpose, not a leak.
+
 **Content Tiers:**
 
 | Tier | Description | Example |

package/README.md

@@ -1,4 +1,4 @@
-# PAI Knowledge OS — v0.9.7
+# PAI Knowledge OS — v0.9.10
 
 Claude Code has a memory problem. Every new session starts cold — no idea what you built yesterday, what decisions you made, or where you left off. PAI fixes this.
 
@@ -393,6 +393,53 @@ This reveals unexpected intellectual bridges: the same concurrency pattern used
 
 ---
 
+## Memory Architecture
+
+PAI's memory system uses a three-tier hybrid store inspired by Cognee's approach to knowledge graphs and retrieval. Each tier has a distinct role, and they work together to answer queries that no single store could handle alone.
+
+### Three-Tier Hybrid Store
+
+| Tier | Backend | What it stores |
+|------|---------|----------------|
+| **Chunks + entities** | SQLite (simple mode) or PostgreSQL (full mode) | Text chunks with embeddings; named entity records with content-address hashes |
+| **Knowledge graph** | PostgreSQL (`kg_triples`) | Subject-predicate-object triples with `valid_from`/`valid_to` timestamps |
+| **Vector embeddings** | pgvector (full mode) | 768-dimensional Snowflake Arctic embeddings on chunks and vault notes |
+
+### Entity Deduplication via Content-Address Hashing
+
+Named entities (people, projects, libraries, concepts) extracted during indexing are stored in a `kg_entities` table and deduplicated using a content-address hash derived from the entity's canonical name. Two mentions of "PostgreSQL" in different session notes resolve to a single entity row — the hash acts as a stable identity, so the graph stays normalized even as new content is indexed.
+
+### Graph-Completion Search Pipeline
+
+Standard vector search finds semantically similar chunks. Graph-completion search goes further:
+
+1. **Vector seeds** — a semantic search returns the top-K most relevant chunks.
+2. **Graph traversal** — the entities mentioned in those chunks are looked up in `kg_triples`; their immediate neighbors are fetched (one hop).
+3. **Candidate expansion** — the neighbor entities' associated chunks are added to the result set.
+4. **Re-rank** — the expanded candidate set is re-scored by the cross-encoder, which reads each (query, result) pair together. Results are sorted by this final relevance score.
+
+This means a query about "the PAI daemon" can surface a session note that mentions the daemon only indirectly — because a connected entity (the Unix socket, the launchd service) appears in both the graph and the note.
+
+### Feedback Loop with Relevance Scoring
+
+Every search result that is subsequently retrieved via `memory_get` (i.e., actually read by the model) generates a positive feedback signal. These signals are stored and used to adjust future search weights using an exponential moving average (EMA):
+
+```
+new_weight = alpha * signal + (1 - alpha) * old_weight
+```
+
+The default alpha is 0.1, so recent positive signals gradually raise a chunk's effective score without overriding the semantic baseline. This creates a personalization loop: content you actually use rises in future rankings; content you skip does not.
+
+### Access Timestamp Tracking
+
+Every chunk row carries a `last_accessed_at` timestamp updated on each `memory_get` call. This supports recency boost (content accessed recently scores higher) and enables future eviction policies for very large knowledge bases.
+
+### Multi-Tenant Support
+
+PAI isolates memory by project. Every chunk, entity, and observation row carries a `project_id` foreign key. Searches default to the current project; the `all_projects: true` flag (or `--all` CLI option) lifts the filter. Knowledge-graph triples carry a `project_id` as well, so cross-project tunnels (`memory_tunnels`) are detected explicitly rather than accidentally.
+
+---
+
 ## Automatic Observation Capture
 
 PAI automatically classifies and stores every significant tool call during your sessions. When you edit a file, run a command, or make a decision, PAI captures it as a structured observation — building a searchable timeline of everything you've done across all projects.
@@ -754,7 +801,7 @@ External URLs (`https://`, `mailto:`, etc.) are excluded — only relative paths
 
 ## Release History
 
-18 releases shipped from v0.7.2 to v0.9.7 (March 19 – April 10, 2026):
+21 releases shipped from v0.7.2 to v0.9.10 (March 19 – April 13, 2026):
 
 | Version | Feature |
 |---------|---------|
@@ -779,6 +826,9 @@ External URLs (`https://`, `mailto:`, etc.) are excluded — only relative paths
 | v0.9.5 | Budget-aware advisor mode |
 | v0.9.6 | Statusline auto-writes budget to advisor |
 | v0.9.7 | Advisor mode label in statusline, natural language mode switching |
+| v0.9.8 | Privacy tags, compact search format, npx install |
+| v0.9.9 | Fix advisor mode to delegate to haiku instead of hoarding in opus |
+| v0.9.10 | Cognee-inspired three-tier memory: entity deduplication, graph-completion search, feedback EMA |
 
 ---
 
@@ -800,6 +850,8 @@ PAI Knowledge OS is inspired by [Daniel Miessler](https://github.com/danielmiess
 
 The automatic observation capture system — classifying tool calls into structured observations with progressive context injection — is inspired by [claude-mem](https://github.com/thedotmack/claude-mem) by [thedotmack](https://github.com/thedotmack). claude-mem demonstrated that automatic memory capture during Claude Code sessions dramatically improves continuity. PAI adapts this concept with a rule-based classifier, PostgreSQL storage, and three-layer progressive disclosure.
 
+The three-store hybrid memory architecture — combining SQLite/PostgreSQL chunks with a knowledge graph and vector embeddings, graph-completion search (vector seeds → graph traversal → re-rank), and the feedback EMA relevance loop — is inspired by [Cognee](https://github.com/topoteretes/cognee) by [topoteretes](https://github.com/topoteretes). Cognee showed that unifying structured knowledge graphs with unstructured vector retrieval produces dramatically better recall. PAI adapts this pattern to the personal knowledge OS context with project-scoped multi-tenancy and content-address entity deduplication.
+
 ---
 
 ## License

package/dist/{auto-route-CruBrTf-.mjs → auto-route-DL4ViDKC.mjs}

@@ -26,7 +26,7 @@ async function autoRoute(registryDb, federation, cwd, context) {
 	const markerResult = findMarkerUpward(registryDb, target);
 	if (markerResult) return markerResult;
 	if (context && context.trim().length > 0) {
-		const { detectTopicShift } = await import("./detector-CNU3zCwP.mjs").then((n) => n.n);
+		const { detectTopicShift } = await import("./detector-AzVtGLtL.mjs").then((n) => n.n);
 		const topicResult = await detectTopicShift(registryDb, federation, {
 			context,
 			threshold: .5
@@ -83,4 +83,4 @@ function formatAutoRouteJson(result) {
 
 //#endregion
 export { autoRoute, formatAutoRouteJson };
-//# sourceMappingURL=auto-route-CruBrTf-.mjs.map
+//# sourceMappingURL=auto-route-DL4ViDKC.mjs.map

package/dist/{auto-route-CruBrTf-.mjs.map → auto-route-DL4ViDKC.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"auto-route-CruBrTf-.mjs","names":[],"sources":["../src/session/auto-route.ts"],"sourcesContent":["/**\n * Auto-route: automatic project routing suggestion on session start.\n *\n * Given a working directory (and optional conversation context), determine\n * which registered project the session belongs to.\n *\n * Strategy (in priority order):\n *   1. Path match   — exact or parent-directory match in the project registry\n *   2. Marker walk  — walk up from cwd looking for Notes/PAI.md, resolve slug\n *   3. Topic match  — BM25 keyword search against memory (requires context text)\n *\n * The function is stateless and works with direct DB access (no daemon\n * required), making it fast and safe to call during session startup.\n */\n\nimport type { Database } from \"better-sqlite3\";\nimport type { StorageBackend } from \"../storage/interface.js\";\nimport { resolve, dirname } from \"node:path\";\nimport { existsSync } from \"node:fs\";\nimport { readPaiMarker } from \"../registry/pai-marker.js\";\nimport { detectProject } from \"../cli/commands/detect.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type AutoRouteMethod = \"path\" | \"marker\" | \"topic\";\n\nexport interface AutoRouteResult {\n  /** Project slug */\n  slug: string;\n  /** Human-readable project name */\n  display_name: string;\n  /** Absolute path to the project root */\n  root_path: string;\n  /** How the project was detected */\n  method: AutoRouteMethod;\n  /** Confidence [0,1]: 1.0 for path/marker matches, BM25 fraction for topic */\n  confidence: number;\n}\n\n// ---------------------------------------------------------------------------\n// Core function\n// ---------------------------------------------------------------------------\n\n/**\n * Determine which project a session should be routed to.\n *\n * @param registryDb  Open PAI registry database\n * @param federation  Memory storage backend (needed only for topic fallback)\n * @param cwd         Working directory to detect from (defaults to process.cwd())\n * @param context     Optional conversation text for topic-based fallback\n * @returns           Best project match, or null if nothing matched\n */\nexport async function autoRoute(\n  registryDb: Database,\n  federation: Database | StorageBackend,\n  cwd?: string,\n  context?: string\n): Promise<AutoRouteResult | null> {\n  const target = resolve(cwd ?? process.cwd());\n\n  // -------------------------------------------------------------------------\n  // Strategy 1: Path match via registry\n  // -------------------------------------------------------------------------\n\n  const pathMatch = detectProject(registryDb, target);\n\n  if (pathMatch) {\n    return {\n      slug: pathMatch.slug,\n      display_name: pathMatch.display_name,\n      root_path: pathMatch.root_path,\n      method: \"path\",\n      confidence: 1.0,\n    };\n  }\n\n  // -------------------------------------------------------------------------\n  // Strategy 2: PAI.md marker file walk\n  //\n  // Walk up from cwd, checking <dir>/Notes/PAI.md at each level.\n  // Once found, resolve the slug against the registry to get full project info.\n  // -------------------------------------------------------------------------\n\n  const markerResult = findMarkerUpward(registryDb, target);\n  if (markerResult) {\n    return markerResult;\n  }\n\n  // -------------------------------------------------------------------------\n  // Strategy 3: Topic detection (requires context text)\n  // -------------------------------------------------------------------------\n\n  if (context && context.trim().length > 0) {\n    // Lazy import to avoid bundler pulling in daemon/index.mjs at module load time\n    const { detectTopicShift } = await import(\"../topics/detector.js\");\n    const topicResult = await detectTopicShift(registryDb, federation, {\n      context,\n      threshold: 0.5, // Lower threshold for initial routing (vs shift detection)\n    });\n\n    if (topicResult.suggestedProject && topicResult.confidence > 0) {\n      // Look up the full project info from the registry\n      const projectRow = registryDb\n        .prepare(\n          \"SELECT slug, display_name, root_path FROM projects WHERE slug = ? AND status != 'archived'\"\n        )\n        .get(topicResult.suggestedProject) as\n        | { slug: string; display_name: string; root_path: string }\n        | undefined;\n\n      if (projectRow) {\n        return {\n          slug: projectRow.slug,\n          display_name: projectRow.display_name,\n          root_path: projectRow.root_path,\n          method: \"topic\",\n          confidence: topicResult.confidence,\n        };\n      }\n    }\n  }\n\n  return null;\n}\n\n// ---------------------------------------------------------------------------\n// Marker walk helper\n// ---------------------------------------------------------------------------\n\n/**\n * Walk up the directory tree from `startDir`, checking each level for a\n * `Notes/PAI.md` file. If found, read the slug and look up the project.\n *\n * Stops at the filesystem root or after 20 levels (safety guard).\n */\nfunction findMarkerUpward(\n  registryDb: Database,\n  startDir: string\n): AutoRouteResult | null {\n  let current = startDir;\n  let depth = 0;\n\n  while (depth < 20) {\n    const markerPath = `${current}/Notes/PAI.md`;\n\n    if (existsSync(markerPath)) {\n      const marker = readPaiMarker(current);\n\n      if (marker && marker.status !== \"archived\") {\n        // Resolve slug to full project info in the registry\n        const projectRow = registryDb\n          .prepare(\n            \"SELECT slug, display_name, root_path FROM projects WHERE slug = ? AND status != 'archived'\"\n          )\n          .get(marker.slug) as\n          | { slug: string; display_name: string; root_path: string }\n          | undefined;\n\n        if (projectRow) {\n          return {\n            slug: projectRow.slug,\n            display_name: projectRow.display_name,\n            root_path: projectRow.root_path,\n            method: \"marker\",\n            confidence: 1.0,\n          };\n        }\n      }\n    }\n\n    const parent = dirname(current);\n    if (parent === current) break; // Reached filesystem root\n    current = parent;\n    depth++;\n  }\n\n  return null;\n}\n\n// ---------------------------------------------------------------------------\n// Format helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Format an AutoRouteResult as a human-readable string for CLI output.\n */\nexport function formatAutoRoute(result: AutoRouteResult): string {\n  const lines: string[] = [\n    `slug:         ${result.slug}`,\n    `display_name: ${result.display_name}`,\n    `root_path:    ${result.root_path}`,\n    `method:       ${result.method}`,\n    `confidence:   ${(result.confidence * 100).toFixed(0)}%`,\n  ];\n  return lines.join(\"\\n\");\n}\n\n/**\n * Format an AutoRouteResult as JSON for machine consumption.\n */\nexport function formatAutoRouteJson(result: AutoRouteResult): string {\n  return JSON.stringify(result, null, 2);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAsDA,eAAsB,UACpB,YACA,YACA,KACA,SACiC;CACjC,MAAM,SAAS,QAAQ,OAAO,QAAQ,KAAK,CAAC;CAM5C,MAAM,YAAY,cAAc,YAAY,OAAO;AAEnD,KAAI,UACF,QAAO;EACL,MAAM,UAAU;EAChB,cAAc,UAAU;EACxB,WAAW,UAAU;EACrB,QAAQ;EACR,YAAY;EACb;CAUH,MAAM,eAAe,iBAAiB,YAAY,OAAO;AACzD,KAAI,aACF,QAAO;AAOT,KAAI,WAAW,QAAQ,MAAM,CAAC,SAAS,GAAG;EAExC,MAAM,EAAE,qBAAqB,MAAM,OAAO;EAC1C,MAAM,cAAc,MAAM,iBAAiB,YAAY,YAAY;GACjE;GACA,WAAW;GACZ,CAAC;AAEF,MAAI,YAAY,oBAAoB,YAAY,aAAa,GAAG;GAE9D,MAAM,aAAa,WAChB,QACC,6FACD,CACA,IAAI,YAAY,iBAAiB;AAIpC,OAAI,WACF,QAAO;IACL,MAAM,WAAW;IACjB,cAAc,WAAW;IACzB,WAAW,WAAW;IACtB,QAAQ;IACR,YAAY,YAAY;IACzB;;;AAKP,QAAO;;;;;;;;AAaT,SAAS,iBACP,YACA,UACwB;CACxB,IAAI,UAAU;CACd,IAAI,QAAQ;AAEZ,QAAO,QAAQ,IAAI;AAGjB,MAAI,WAFe,GAAG,QAAQ,eAEJ,EAAE;GAC1B,MAAM,SAAS,cAAc,QAAQ;AAErC,OAAI,UAAU,OAAO,WAAW,YAAY;IAE1C,MAAM,aAAa,WAChB,QACC,6FACD,CACA,IAAI,OAAO,KAAK;AAInB,QAAI,WACF,QAAO;KACL,MAAM,WAAW;KACjB,cAAc,WAAW;KACzB,WAAW,WAAW;KACtB,QAAQ;KACR,YAAY;KACb;;;EAKP,MAAM,SAAS,QAAQ,QAAQ;AAC/B,MAAI,WAAW,QAAS;AACxB,YAAU;AACV;;AAGF,QAAO;;;;;AAwBT,SAAgB,oBAAoB,QAAiC;AACnE,QAAO,KAAK,UAAU,QAAQ,MAAM,EAAE"}
+{"version":3,"file":"auto-route-DL4ViDKC.mjs","names":[],"sources":["../src/session/auto-route.ts"],"sourcesContent":["/**\n * Auto-route: automatic project routing suggestion on session start.\n *\n * Given a working directory (and optional conversation context), determine\n * which registered project the session belongs to.\n *\n * Strategy (in priority order):\n *   1. Path match   — exact or parent-directory match in the project registry\n *   2. Marker walk  — walk up from cwd looking for Notes/PAI.md, resolve slug\n *   3. Topic match  — BM25 keyword search against memory (requires context text)\n *\n * The function is stateless and works with direct DB access (no daemon\n * required), making it fast and safe to call during session startup.\n */\n\nimport type { Database } from \"better-sqlite3\";\nimport type { StorageBackend } from \"../storage/interface.js\";\nimport { resolve, dirname } from \"node:path\";\nimport { existsSync } from \"node:fs\";\nimport { readPaiMarker } from \"../registry/pai-marker.js\";\nimport { detectProject } from \"../cli/commands/detect.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type AutoRouteMethod = \"path\" | \"marker\" | \"topic\";\n\nexport interface AutoRouteResult {\n  /** Project slug */\n  slug: string;\n  /** Human-readable project name */\n  display_name: string;\n  /** Absolute path to the project root */\n  root_path: string;\n  /** How the project was detected */\n  method: AutoRouteMethod;\n  /** Confidence [0,1]: 1.0 for path/marker matches, BM25 fraction for topic */\n  confidence: number;\n}\n\n// ---------------------------------------------------------------------------\n// Core function\n// ---------------------------------------------------------------------------\n\n/**\n * Determine which project a session should be routed to.\n *\n * @param registryDb  Open PAI registry database\n * @param federation  Memory storage backend (needed only for topic fallback)\n * @param cwd         Working directory to detect from (defaults to process.cwd())\n * @param context     Optional conversation text for topic-based fallback\n * @returns           Best project match, or null if nothing matched\n */\nexport async function autoRoute(\n  registryDb: Database,\n  federation: Database | StorageBackend,\n  cwd?: string,\n  context?: string\n): Promise<AutoRouteResult | null> {\n  const target = resolve(cwd ?? process.cwd());\n\n  // -------------------------------------------------------------------------\n  // Strategy 1: Path match via registry\n  // -------------------------------------------------------------------------\n\n  const pathMatch = detectProject(registryDb, target);\n\n  if (pathMatch) {\n    return {\n      slug: pathMatch.slug,\n      display_name: pathMatch.display_name,\n      root_path: pathMatch.root_path,\n      method: \"path\",\n      confidence: 1.0,\n    };\n  }\n\n  // -------------------------------------------------------------------------\n  // Strategy 2: PAI.md marker file walk\n  //\n  // Walk up from cwd, checking <dir>/Notes/PAI.md at each level.\n  // Once found, resolve the slug against the registry to get full project info.\n  // -------------------------------------------------------------------------\n\n  const markerResult = findMarkerUpward(registryDb, target);\n  if (markerResult) {\n    return markerResult;\n  }\n\n  // -------------------------------------------------------------------------\n  // Strategy 3: Topic detection (requires context text)\n  // -------------------------------------------------------------------------\n\n  if (context && context.trim().length > 0) {\n    // Lazy import to avoid bundler pulling in daemon/index.mjs at module load time\n    const { detectTopicShift } = await import(\"../topics/detector.js\");\n    const topicResult = await detectTopicShift(registryDb, federation, {\n      context,\n      threshold: 0.5, // Lower threshold for initial routing (vs shift detection)\n    });\n\n    if (topicResult.suggestedProject && topicResult.confidence > 0) {\n      // Look up the full project info from the registry\n      const projectRow = registryDb\n        .prepare(\n          \"SELECT slug, display_name, root_path FROM projects WHERE slug = ? AND status != 'archived'\"\n        )\n        .get(topicResult.suggestedProject) as\n        | { slug: string; display_name: string; root_path: string }\n        | undefined;\n\n      if (projectRow) {\n        return {\n          slug: projectRow.slug,\n          display_name: projectRow.display_name,\n          root_path: projectRow.root_path,\n          method: \"topic\",\n          confidence: topicResult.confidence,\n        };\n      }\n    }\n  }\n\n  return null;\n}\n\n// ---------------------------------------------------------------------------\n// Marker walk helper\n// ---------------------------------------------------------------------------\n\n/**\n * Walk up the directory tree from `startDir`, checking each level for a\n * `Notes/PAI.md` file. If found, read the slug and look up the project.\n *\n * Stops at the filesystem root or after 20 levels (safety guard).\n */\nfunction findMarkerUpward(\n  registryDb: Database,\n  startDir: string\n): AutoRouteResult | null {\n  let current = startDir;\n  let depth = 0;\n\n  while (depth < 20) {\n    const markerPath = `${current}/Notes/PAI.md`;\n\n    if (existsSync(markerPath)) {\n      const marker = readPaiMarker(current);\n\n      if (marker && marker.status !== \"archived\") {\n        // Resolve slug to full project info in the registry\n        const projectRow = registryDb\n          .prepare(\n            \"SELECT slug, display_name, root_path FROM projects WHERE slug = ? AND status != 'archived'\"\n          )\n          .get(marker.slug) as\n          | { slug: string; display_name: string; root_path: string }\n          | undefined;\n\n        if (projectRow) {\n          return {\n            slug: projectRow.slug,\n            display_name: projectRow.display_name,\n            root_path: projectRow.root_path,\n            method: \"marker\",\n            confidence: 1.0,\n          };\n        }\n      }\n    }\n\n    const parent = dirname(current);\n    if (parent === current) break; // Reached filesystem root\n    current = parent;\n    depth++;\n  }\n\n  return null;\n}\n\n// ---------------------------------------------------------------------------\n// Format helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Format an AutoRouteResult as a human-readable string for CLI output.\n */\nexport function formatAutoRoute(result: AutoRouteResult): string {\n  const lines: string[] = [\n    `slug:         ${result.slug}`,\n    `display_name: ${result.display_name}`,\n    `root_path:    ${result.root_path}`,\n    `method:       ${result.method}`,\n    `confidence:   ${(result.confidence * 100).toFixed(0)}%`,\n  ];\n  return lines.join(\"\\n\");\n}\n\n/**\n * Format an AutoRouteResult as JSON for machine consumption.\n */\nexport function formatAutoRouteJson(result: AutoRouteResult): string {\n  return JSON.stringify(result, null, 2);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAsDA,eAAsB,UACpB,YACA,YACA,KACA,SACiC;CACjC,MAAM,SAAS,QAAQ,OAAO,QAAQ,KAAK,CAAC;CAM5C,MAAM,YAAY,cAAc,YAAY,OAAO;AAEnD,KAAI,UACF,QAAO;EACL,MAAM,UAAU;EAChB,cAAc,UAAU;EACxB,WAAW,UAAU;EACrB,QAAQ;EACR,YAAY;EACb;CAUH,MAAM,eAAe,iBAAiB,YAAY,OAAO;AACzD,KAAI,aACF,QAAO;AAOT,KAAI,WAAW,QAAQ,MAAM,CAAC,SAAS,GAAG;EAExC,MAAM,EAAE,qBAAqB,MAAM,OAAO;EAC1C,MAAM,cAAc,MAAM,iBAAiB,YAAY,YAAY;GACjE;GACA,WAAW;GACZ,CAAC;AAEF,MAAI,YAAY,oBAAoB,YAAY,aAAa,GAAG;GAE9D,MAAM,aAAa,WAChB,QACC,6FACD,CACA,IAAI,YAAY,iBAAiB;AAIpC,OAAI,WACF,QAAO;IACL,MAAM,WAAW;IACjB,cAAc,WAAW;IACzB,WAAW,WAAW;IACtB,QAAQ;IACR,YAAY,YAAY;IACzB;;;AAKP,QAAO;;;;;;;;AAaT,SAAS,iBACP,YACA,UACwB;CACxB,IAAI,UAAU;CACd,IAAI,QAAQ;AAEZ,QAAO,QAAQ,IAAI;AAGjB,MAAI,WAFe,GAAG,QAAQ,eAEJ,EAAE;GAC1B,MAAM,SAAS,cAAc,QAAQ;AAErC,OAAI,UAAU,OAAO,WAAW,YAAY;IAE1C,MAAM,aAAa,WAChB,QACC,6FACD,CACA,IAAI,OAAO,KAAK;AAInB,QAAI,WACF,QAAO;KACL,MAAM,WAAW;KACjB,cAAc,WAAW;KACzB,WAAW,WAAW;KACtB,QAAQ;KACR,YAAY;KACb;;;EAKP,MAAM,SAAS,QAAQ,QAAQ;AAC/B,MAAI,WAAW,QAAS;AACxB,YAAU;AACV;;AAGF,QAAO;;;;;AAwBT,SAAgB,oBAAoB,QAAiC;AACnE,QAAO,KAAK,UAAU,QAAQ,MAAM,EAAE"}

package/dist/cli/index.mjs

@@ -3,18 +3,18 @@ import { n as openRegistry } from "../db-BtuN768f.mjs";
 import { _ as warn, a as fmtDate, c as ok, d as scaffoldProjectDirs, f as shortenPath, i as err, l as renderTable, m as slugify, n as dim, o as header, p as slugFromPath, r as encodeDir, s as now, t as bold, u as resolvePath } from "../utils-QSfKagcj.mjs";
 import { a as slugify$1, i as parseSessionFilename, n as decodeEncodedDir, t as buildEncodedDirMap } from "../migrate-jokLenje.mjs";
 import { n as ensurePaiMarker, t as discoverPaiMarkers } from "../pai-marker-CXQPX2P6.mjs";
-import { n as openFederation } from "../db-DdUperSl.mjs";
+import { n as openFederation } from "../db-CYmBWcjh.mjs";
 import "../helpers-OCVFgprQ.mjs";
 import { i as indexProject, n as indexAll, t as embedChunks } from "../sync-CdHSL9Kc.mjs";
 import "../embeddings-DGRAPAYb.mjs";
 import { t as STOP_WORDS } from "../stop-words-BaMEGVeY.mjs";
-import { n as populateSlugs, r as searchMemory } from "../search-DC1qhkKn.mjs";
+import { n as populateSlugs, r as searchMemory } from "../search-i2nlQ-JM.mjs";
 import { n as formatDetection, r as formatDetectionJson, t as detectProject } from "../detect-CdaA48EI.mjs";
-import { t as extractAndStoreTriples } from "../kg-extraction-BlGM40q7.mjs";
+import { t as extractAndStoreTriples } from "../kg-extraction-Uvr9fTlz.mjs";
 import { t as PaiClient } from "../ipc-client-CoyUHPod.mjs";
 import { a as expandHome, i as ensureConfigDir, n as CONFIG_FILE$2, o as loadConfig, t as CONFIG_DIR } from "../config-BuhHWyOK.mjs";
-import { t as createStorageBackend } from "../factory-DKDPRhAN.mjs";
-import { i as kgQuery } from "../kg-B5ysyRLC.mjs";
+import { t as createStorageBackend } from "../factory-BDBIfTDC.mjs";
+import { s as kgQuery } from "../kg-entity-D5v7RCDi.mjs";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, platform, tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
@@ -1682,9 +1682,9 @@ function cmdActive(db, opts) {
 	], rows));
 }
 async function cmdAutoRoute(opts) {
-	const { autoRoute, formatAutoRoute, formatAutoRouteJson } = await import("../auto-route-CruBrTf-.mjs");
+	const { autoRoute, formatAutoRoute, formatAutoRouteJson } = await import("../auto-route-DL4ViDKC.mjs");
 	const { openRegistry } = await import("../db-BtuN768f.mjs").then((n) => n.t);
-	const { createStorageBackend } = await import("../factory-DKDPRhAN.mjs").then((n) => n.n);
+	const { createStorageBackend } = await import("../factory-BDBIfTDC.mjs").then((n) => n.n);
 	const { loadConfig } = await import("../config-BuhHWyOK.mjs").then((n) => n.r);
 	const config = loadConfig();
 	const registryDb = openRegistry();
@@ -3245,7 +3245,7 @@ function registerSearchCommand(memoryCmd, getDb) {
 		}
 		const recencyDays = parseInt(opts.recency ?? String(searchConfig.recencyBoostDays), 10);
 		if (recencyDays > 0) {
-			const { applyRecencyBoost } = await import("../search-DC1qhkKn.mjs").then((n) => n.o);
+			const { applyRecencyBoost } = await import("../search-i2nlQ-JM.mjs").then((n) => n.o);
 			console.log(dim(`Applying recency boost (half-life: ${recencyDays} days)...`));
 			results = applyRecencyBoost(results, recencyDays);
 		}
@@ -3794,7 +3794,7 @@ function cmdLogs(opts) {
 }
 function registerDaemonCommands(daemonCmd) {
 	daemonCmd.command("serve").description("Start the PAI daemon in the foreground").action(async () => {
-		const { serve } = await import("../daemon-WQY1kwOF.mjs").then((n) => n.t);
+		const { serve } = await import("../daemon-dYymOnwd.mjs").then((n) => n.t);
 		const { loadConfig: lc, ensureConfigDir } = await import("../config-BuhHWyOK.mjs").then((n) => n.r);
 		ensureConfigDir();
 		await serve(lc());
@@ -5151,6 +5151,10 @@ async function stepSettings(rl, daName) {
 			DA: daName
 		},
 		hooks: [
+			{
+				hookType: "SessionStart",
+				command: "${PAI_DIR}/Hooks/session-commands.mjs"
+			},
 			{
 				hookType: "SessionStart",
 				command: "${PAI_DIR}/Hooks/load-core-context.mjs"
@@ -7659,6 +7663,7 @@ async function backfillKgFromNotes(options = {}) {
 	const backend = await createStorageBackend(config);
 	if (backend.backendType !== "postgres") throw new Error("Postgres backend unavailable — fell back to SQLite. Cannot backfill KG.");
 	const pool = backend.getPool();
+	const federationDb = openFederation();
 	const registry = openRegistry();
 	let projects;
 	try {
@@ -7705,7 +7710,8 @@ async function backfillKgFromNotes(options = {}) {
 				projectId: project.id,
 				sessionId: `backfill:${notePath}`,
 				gitLog: "",
-				model: "sonnet"
+				model: "sonnet",
+				federationDb
 			});
 			result.notes_processed++;
 			result.triples_extracted += stats.extracted;
@@ -7719,13 +7725,14 @@ async function backfillKgFromNotes(options = {}) {
 		}
 	}
 	if (!options.dryRun) saveState(state);
+	federationDb.close();
 	await backend.close();
 	return result;
 }
 
 //#endregion
 //#region src/cli/commands/kg.ts
-async function getPool() {
+async function getPool$1() {
 	const config = loadConfig();
 	if (config.storageBackend !== "postgres") {
 		console.error(err("  KG commands require Postgres backend."));
@@ -7782,8 +7789,8 @@ async function cmdBackfill(opts) {
 		process.exit(1);
 	}
 }
-async function cmdQuery(opts) {
-	const { pool, close } = await getPool();
+async function cmdQuery$1(opts) {
+	const { pool, close } = await getPool$1();
 	try {
 		let projectId;
 		if (opts.project) {
@@ -7821,7 +7828,7 @@ async function cmdQuery(opts) {
 }
 async function cmdList(opts) {
 	const limit = opts.limit ? parseInt(opts.limit, 10) : 50;
-	const { pool, close } = await getPool();
+	const { pool, close } = await getPool$1();
 	try {
 		let projectId;
 		if (opts.project) {
@@ -7844,7 +7851,7 @@ async function cmdList(opts) {
 	}
 }
 async function cmdStats() {
-	const { pool, close } = await getPool();
+	const { pool, close } = await getPool$1();
 	try {
 		const totals = await pool.query(`SELECT
          COUNT(*)::text                                            AS total,
@@ -7880,7 +7887,7 @@ function registerKgCommands(kgCmd) {
 		await cmdBackfill(opts);
 	});
 	kgCmd.command("query").description("Query KG triples by subject, predicate, object, time, or project").option("--subject <s>", "Filter by subject").option("--predicate <p>", "Filter by predicate").option("--object <o>", "Filter by object").option("--as-of <date>", "Point-in-time query (YYYY-MM-DD or ISO 8601)").option("--project <slug>", "Restrict to a project slug").option("--json", "Output raw JSON").action(async (opts) => {
-		await cmdQuery(opts);
+		await cmdQuery$1(opts);
 	});
 	kgCmd.command("list").description("List currently-valid triples").option("--project <slug>", "Restrict to a project slug").option("--limit <n>", "Maximum triples to print", "50").action(async (opts) => {
 		await cmdList(opts);
@@ -7890,6 +7897,232 @@ function registerKgCommands(kgCmd) {
 	});
 }
 
+//#endregion
+//#region src/cli/commands/db.ts
+function getSqliteDb() {
+	return openFederation();
+}
+function sqliteQuery(sql) {
+	const db = getSqliteDb();
+	try {
+		const raw = db.prepare(sql).all();
+		if (raw.length === 0) return {
+			columns: [],
+			rows: []
+		};
+		const columns = Object.keys(raw[0]);
+		return {
+			columns,
+			rows: raw.map((r) => columns.map((c) => r[c]))
+		};
+	} finally {
+		db.close();
+	}
+}
+function sqliteTables() {
+	const db = getSqliteDb();
+	try {
+		return db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all().map((r) => r.name);
+	} finally {
+		db.close();
+	}
+}
+function sqliteSchema(table) {
+	const db = getSqliteDb();
+	try {
+		if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table)) throw new Error(`Invalid table name: ${table}`);
+		const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+		if (rows.length === 0) throw new Error(`Table not found: ${table}`);
+		return {
+			columns: [
+				"cid",
+				"name",
+				"type",
+				"notnull",
+				"default",
+				"pk"
+			],
+			data: rows.map((r) => [
+				r.cid,
+				r.name,
+				r.type,
+				r.notnull ? "NOT NULL" : "",
+				r.dflt_value ?? "",
+				r.pk ? "PK" : ""
+			])
+		};
+	} finally {
+		db.close();
+	}
+}
+async function getPool() {
+	const pgConfig = loadConfig().postgres ?? {};
+	const { Pool } = await import("pg");
+	const pool = new Pool(pgConfig.connectionString ? { connectionString: pgConfig.connectionString } : {
+		host: pgConfig.host ?? "localhost",
+		port: pgConfig.port ?? 5432,
+		database: pgConfig.database ?? "pai",
+		user: pgConfig.user ?? "pai",
+		password: pgConfig.password ?? "pai",
+		connectionTimeoutMillis: pgConfig.connectionTimeoutMs ?? 5e3
+	});
+	try {
+		(await pool.connect()).release();
+	} catch (e) {
+		await pool.end();
+		const msg = e instanceof Error ? e.message : String(e);
+		throw new Error(`Cannot connect to Postgres: ${msg}`);
+	}
+	return pool;
+}
+async function postgresQuery(sql) {
+	const pool = await getPool();
+	try {
+		const result = await pool.query(sql);
+		const columns = result.fields.map((f) => f.name);
+		return {
+			columns,
+			rows: result.rows.map((r) => columns.map((c) => r[c]))
+		};
+	} finally {
+		await pool.end();
+	}
+}
+async function postgresTables() {
+	const pool = await getPool();
+	try {
+		return (await pool.query("SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename")).rows.map((r) => r.tablename);
+	} finally {
+		await pool.end();
+	}
+}
+async function postgresSchema(table) {
+	const pool = await getPool();
+	try {
+		const result = await pool.query(`SELECT column_name, data_type, is_nullable, column_default
+       FROM information_schema.columns
+       WHERE table_schema = 'public' AND table_name = $1
+       ORDER BY ordinal_position`, [table]);
+		if (result.rows.length === 0) throw new Error(`Table not found in public schema: ${table}`);
+		return {
+			columns: [
+				"column",
+				"type",
+				"nullable",
+				"default"
+			],
+			rows: result.rows.map((r) => [
+				r.column_name,
+				r.data_type,
+				r.is_nullable === "YES" ? "YES" : "NO",
+				r.column_default ?? ""
+			])
+		};
+	} finally {
+		await pool.end();
+	}
+}
+function printResult(result, json) {
+	if (json) {
+		const objects = result.rows.map((row) => {
+			const obj = {};
+			result.columns.forEach((col, i) => {
+				obj[col] = row[i];
+			});
+			return obj;
+		});
+		console.log(JSON.stringify(objects, null, 2));
+		return;
+	}
+	if (result.rows.length === 0) {
+		console.log();
+		console.log(dim("  (no rows)"));
+		console.log();
+		return;
+	}
+	const stringRows = result.rows.map((row) => row.map((cell) => {
+		if (cell === null || cell === void 0) return dim("NULL");
+		if (typeof cell === "object") return JSON.stringify(cell);
+		return String(cell);
+	}));
+	console.log();
+	console.log(renderTable(result.columns, stringRows));
+	console.log();
+	console.log(dim(`  ${result.rows.length} row(s)`));
+	console.log();
+}
+async function cmdQuery(sql, opts) {
+	const target = opts.db ?? "sqlite";
+	console.log();
+	console.log(header(`  Query [${target}]`) + dim(`  ${sql.slice(0, 80)}${sql.length > 80 ? "…" : ""}`));
+	try {
+		let result;
+		if (target === "postgres") result = await postgresQuery(sql);
+		else result = sqliteQuery(sql);
+		printResult(result, opts.json ?? false);
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		console.error(err(`  ${msg}`));
+		process.exit(1);
+	}
+}
+async function cmdTables(opts) {
+	const target = opts.db ?? "sqlite";
+	console.log();
+	console.log(header(`  Tables [${target}]`));
+	console.log();
+	try {
+		let tables;
+		if (target === "postgres") tables = await postgresTables();
+		else tables = sqliteTables();
+		if (opts.json) {
+			console.log(JSON.stringify(tables, null, 2));
+			return;
+		}
+		if (tables.length === 0) console.log(dim("  (no tables found)"));
+		else for (const t of tables) console.log(`  ${bold(t)}`);
+		console.log();
+		console.log(dim(`  ${tables.length} table(s)`));
+		console.log();
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		console.error(err(`  ${msg}`));
+		process.exit(1);
+	}
+}
+async function cmdSchema(table, opts) {
+	const target = opts.db ?? "sqlite";
+	console.log();
+	console.log(header(`  Schema: ${table} [${target}]`));
+	try {
+		let result;
+		if (target === "postgres") result = await postgresSchema(table);
+		else {
+			const raw = sqliteSchema(table);
+			result = {
+				columns: raw.columns,
+				rows: raw.data
+			};
+		}
+		printResult(result, opts.json ?? false);
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		console.error(err(`  ${msg}`));
+		process.exit(1);
+	}
+}
+function registerDbCommands(dbCmd) {
+	dbCmd.command("query <sql>").description("Run a SQL query against the selected database").option("--db <target>", "Database target: sqlite (default) or postgres", "sqlite").option("--json", "Output results as JSON array").action(async (sql, opts) => {
+		await cmdQuery(sql, opts);
+	});
+	dbCmd.command("tables").description("List all tables in the selected database").option("--db <target>", "Database target: sqlite (default) or postgres", "sqlite").option("--json", "Output as JSON array").action(async (opts) => {
+		await cmdTables(opts);
+	});
+	dbCmd.command("schema <table>").description("Show column schema for a table").option("--db <target>", "Database target: sqlite (default) or postgres", "sqlite").option("--json", "Output as JSON array").action(async (table, opts) => {
+		await cmdSchema(table, opts);
+	});
+}
+
 //#endregion
 //#region src/cli/index.ts
 /**
@@ -7939,6 +8172,7 @@ registerUpdateCommand(program);
 registerNotifyCommands(program.command("notify").description("Notification config: status, get, set, test, send"));
 registerTopicCommands(program.command("topic").description("Topic shift detection: check whether context has drifted to a different project"));
 registerKgCommands(program.command("kg").description("Temporal knowledge graph: backfill, query, list, stats"));
+registerDbCommands(program.command("db").description("Database inspection: query, tables, schema (sqlite or postgres)"));
 registerObsidianCommands(program.command("obsidian").description("Obsidian vault: sync project notes, view status, open in Obsidian"), getDb);
 registerZettelCommands(program.command("zettel").description("Zettelkasten intelligence: explore, surprise, converse, themes, health, suggest"), getDb);
 registerObservationCommands(program.command("observation").description("Observation capture: list, search, and stats"));