@tekmidian/pai 0.8.5 → 0.9.0

package/ARCHITECTURE.md

@@ -250,6 +250,127 @@ Restart Claude Code after installation for the tools to appear.
 
 ---
 
+## Memory Intelligence Layer
+
+These features extend the core memory engine with structured, time-aware, and cross-project intelligence. They ship in PAI v0.8.6, inspired by patterns from [mempalace](https://github.com/milla-jovovich/mempalace).
+
+### 4-Layer Wake-Up Context
+
+The `memory_wakeup` MCP tool loads context progressively at session start. The goal is a meaningful cold-start without flooding the context window.
+
+| Layer | Source | Content |
+|-------|--------|---------|
+| L0 | `~/.pai/identity.txt` | Stable identity: who you are, your style, your key projects |
+| L1 | Recent session notes (registry + filesystem) | Essential story: what you were doing, decisions made, where things stand |
+| L2 | On-demand `memory_search` query | Topic-specific context fetched when needed |
+| L3 | Full `memory_search` with reranking | Deep retrieval for complex questions |
+
+L0 and L1 are injected automatically via the `SessionStart` hook. L2 and L3 are triggered by the model during the session as needed.
+
+**File locations:**
+
+```
+~/.pai/identity.txt          # L0 identity — edit this to describe yourself
+Notes/                       # L1 source — the most recent session notes are read here
+~/.config/pai/config.json    # wakeupL1Count: N controls how many notes are read for L1
+```
+
+### Temporal Knowledge Graph
+
+The `kg_triples` table stores knowledge as typed, time-bounded triples. This allows facts to evolve over time rather than accumulating as a flat, undated collection.
+
+**Schema:**
+
+```sql
+CREATE TABLE kg_triples (
+    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id   UUID NOT NULL,
+    subject     TEXT NOT NULL,
+    predicate   TEXT NOT NULL,
+    object      TEXT NOT NULL,
+    valid_from  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    valid_to    TIMESTAMPTZ,          -- NULL means currently valid
+    confidence  REAL DEFAULT 1.0,
+    source      TEXT,                 -- where this fact came from
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX kg_triples_subject_idx ON kg_triples (tenant_id, subject);
+CREATE INDEX kg_triples_valid_idx   ON kg_triples (tenant_id, valid_from, valid_to);
+```
+
+**MCP tools:**
+
+| Tool | Description |
+|------|-------------|
+| `kg_add` | Add a subject-predicate-object triple with `valid_from` (defaults to now) and optional `valid_to` |
+| `kg_query` | Query triples by subject, predicate, or object; filter by point-in-time (defaults to now) |
+| `kg_invalidate` | Set `valid_to = now()` on a triple, marking it as no longer true |
+| `kg_contradictions` | Surface triples that share a subject and predicate but have conflicting objects within overlapping validity windows |
+
+Contradiction detection uses predicate inversion rules (`uses → not_uses`, `works_at → not_works_at`, etc.) to identify direct contradictions. Fuzzy contradictions (same subject/predicate, different object without an explicit inversion rule) are flagged with lower confidence.
+
+### Memory Taxonomy
+
+`memory_taxonomy` returns a structured overview of the current state of indexed memory:
+
+```json
+{
+  "projects": [
+    { "slug": "pai", "sessions": 142, "chunks": 89341, "last_active": "2026-04-07" }
+  ],
+  "totals": {
+    "projects": 77,
+    "sessions": 1204,
+    "chunks": 449000,
+    "embeddings_coverage": 0.94
+  },
+  "recent_activity": [
+    { "project": "pai", "session": "0142", "date": "2026-04-07", "topic": "Memory Intelligence Layer" }
+  ]
+}
+```
+
+This is used both as a user-facing status tool and as a model-facing context signal — the model can call `memory_taxonomy` to understand what is indexed before deciding how to search.
+
+### Mid-Session Auto-Save
+
+The Stop hook normally fires once at the end of a session. The auto-save feature extends this: the Stop hook also fires every N human messages during a session, pushing a `session-summary` work item to the daemon and blocking the Stop event so the session continues.
+
+**Configuration:**
+
+```bash
+PAI_AUTO_SAVE_INTERVAL=15   # default: 15 human messages between saves
+```
+
+Set in `~/.config/pai/config.json` as `autoSaveInterval` or via the environment variable. Set to `0` to disable mid-session saves.
+
+**Loop prevention:** The hook sets a `stop_hook_active` flag in the work item. The daemon checks this flag before re-queuing save work. This prevents an auto-save from triggering another auto-save in a feedback loop.
+
+### Cross-Project Tunnel Detection
+
+`memory_tunnels` detects concepts that appear across multiple projects by comparing the vocabulary of each project's indexed content.
+
+**SQLite mode:** Uses the FTS5 vocabulary virtual table to extract term frequencies per project, then identifies terms that appear significantly in three or more projects.
+
+**PostgreSQL mode:** Uses `ts_stat()` on each project's `tsvector` content to extract term frequencies, then compares across projects using the same multi-project threshold.
+
+**Output:** A ranked list of concept-tunnel pairs:
+
+```json
+[
+  {
+    "concept": "rate limiting",
+    "projects": ["pai-daemon", "whazaa-mcp", "ringsaday-backend"],
+    "tunnel_strength": 0.87
+  }
+]
+```
+
+Tunnel strength is a normalized score based on term frequency across projects, IDF weighting, and the number of projects involved. Higher is more significant.
+
+---
+
 ## Search Modes
 
 Three modes, selectable via the `--mode` flag on the CLI or the `mode` parameter in MCP tool calls.

package/FEATURE.md

@@ -40,6 +40,11 @@ different direction: persistent memory, session continuity, and deep Claude Code
 | **Automatic session notes** | No | Yes — AI-generated via daemon worker (Opus/Sonnet), topic-based splitting |
 | **Topic-based note splitting** | No | Yes — Jaccard similarity detects topic shifts, creates separate notes |
 | **Whisper rules** | No | Yes — injects critical rules on every prompt, survives compaction and /clear |
+| **4-layer wake-up context** | No | Yes — `memory_wakeup` tool loads identity (L0), recent story (L1), on-demand topic (L2), deep search (L3) |
+| **Temporal knowledge graph** | No | Yes — `kg_add`, `kg_query`, `kg_invalidate`, `kg_contradictions` tools; facts have `valid_from`/`valid_to` timestamps |
+| **Memory taxonomy tool** | No | Yes — `memory_taxonomy` surfaces project/session/chunk counts and recent activity at a glance |
+| **Mid-session auto-save** | No | Yes — Stop hook fires every 15 human messages (configurable via `PAI_AUTO_SAVE_INTERVAL`), saves without ending session |
+| **Cross-project tunnel detection** | No | Yes — `memory_tunnels` finds concepts shared across multiple projects via FTS vocabulary comparison |
 | **Session note reconstruction** | No | Yes — /reconstruct skill retroactively creates notes from JSONL + git history |
 | **Backup / restore** | No | Yes — timestamped pg_dump + registry export |
 | **Multi-session concurrency** | n/a | Yes — daemon multiplexes Claude sessions |

package/README.md

@@ -190,6 +190,60 @@ When spawning headless Claude CLI processes for summarization, the daemon strips
 
 ---
 
+## Progressive Memory Loading
+
+PAI loads context in layers at session start rather than all at once. This keeps early-session latency low while giving Claude everything it needs to be useful immediately.
+
+### The Four Layers
+
+| Layer | What it loads | When |
+|-------|---------------|------|
+| **L0 — Identity** | Your identity file (`~/.pai/identity.txt`) — who you are, your working style, key preferences | Always, at every session start |
+| **L1 — Essential story** | Summaries from the most recent session notes — what you were doing, what decisions were made, where things stand | Always, at session start |
+| **L2 — Topic queries** | On-demand retrieval for the current topic — fetched when a specific question or task is identified | On demand, during the session |
+| **L3 — Deep search** | Full `memory_search` across all indexed content — for when L2 is not enough | On demand, when explicitly needed |
+
+L0 and L1 fire automatically via the `memory_wakeup` MCP tool, which is called by the `SessionStart` hook. L2 and L3 are invoked as needed — the model decides when to go deeper based on the question at hand.
+
+### Configuring Your Identity File
+
+Create `~/.pai/identity.txt` with a short description of yourself and your working style. Claude will see this at every session start. Example:
+
+```
+Matthias. Principal engineer. Work across TypeScript, Dart, and shell scripting.
+Projects: PAI (AI infrastructure), RingsADay (Flutter app), Scribe (MCP server).
+Prefer concise explanations, hate unnecessary hedging.
+```
+
+---
+
+## Advanced Memory Tools
+
+### Temporal Knowledge Graph
+
+Facts change over time. The `kg_triples` table stores knowledge as subject-predicate-object triples with `valid_from` and `valid_to` timestamps, so facts can expire and contradict each other rather than accumulating in an undated blob.
+
+Four MCP tools cover the full lifecycle:
+
+- `kg_add` — Add a fact with a start date (and optional end date)
+- `kg_query` — Query the graph, filtered to facts valid at a given point in time
+- `kg_invalidate` — Mark a fact as no longer true (sets `valid_to`)
+- `kg_contradictions` — Surface facts that directly contradict each other, using predicate inversion rules
+
+Example: "Matthias uses PostgreSQL" added in March; "Matthias uses SQLite" added in April with the March fact invalidated. `kg_query` in April sees only the current fact; `kg_query` for March sees the historical one.
+
+### Memory Taxonomy
+
+`memory_taxonomy` gives a shape-of-memory overview: projects, session counts, chunk counts, embedding coverage, and recent activity. Think of it as a dashboard for your knowledge base — useful both for the model (to understand what it knows) and for you (to audit what is indexed).
+
+### Cross-Project Tunnels
+
+`memory_tunnels` detects concepts that appear across multiple projects. It works by comparing FTS vocabulary in SQLite mode or `ts_stat` output in PostgreSQL mode. When a concept — a library name, a design pattern, a person's name — shows up in three separate projects, PAI surfaces that connection as a tunnel.
+
+This reveals unexpected intellectual bridges: the same concurrency pattern used in PAI's daemon showing up in your Flutter app's state management, or a vendor name appearing in both your notes and your job applications.
+
+---
+
 ## 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.

package/dist/cli/index.mjs

@@ -13,7 +13,7 @@ import { n as formatDetection, r as formatDetectionJson, t as detectProject } fr
 import "../indexer-D53l5d1U.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-BzWfxsvK.mjs";
+import { t as createStorageBackend } from "../factory-e0k1HWuc.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";
@@ -1683,7 +1683,7 @@ function cmdActive(db, opts) {
 async function cmdAutoRoute(opts) {
 	const { autoRoute, formatAutoRoute, formatAutoRouteJson } = await import("../auto-route-C-DrW6BL.mjs");
 	const { openRegistry } = await import("../db-BtuN768f.mjs").then((n) => n.t);
-	const { createStorageBackend } = await import("../factory-BzWfxsvK.mjs").then((n) => n.n);
+	const { createStorageBackend } = await import("../factory-e0k1HWuc.mjs").then((n) => n.n);
 	const { loadConfig } = await import("../config-BuhHWyOK.mjs").then((n) => n.r);
 	const config = loadConfig();
 	const registryDb = openRegistry();
@@ -2302,7 +2302,7 @@ async function countVectorDbPaths(oldPaths) {
 	if (oldPaths.length === 0) return 0;
 	try {
 		const { loadConfig } = await import("../config-BuhHWyOK.mjs").then((n) => n.r);
-		const { PostgresBackend } = await import("../postgres-DbUXNuy_.mjs");
+		const { PostgresBackend } = await import("../postgres-DvEPooLO.mjs");
 		const config = loadConfig();
 		if (config.storageBackend !== "postgres") return 0;
 		const pgBackend = new PostgresBackend(config.postgres ?? {});
@@ -2323,7 +2323,7 @@ async function updateVectorDbPaths(moves) {
 	if (moves.length === 0) return 0;
 	try {
 		const { loadConfig } = await import("../config-BuhHWyOK.mjs").then((n) => n.r);
-		const { PostgresBackend } = await import("../postgres-DbUXNuy_.mjs");
+		const { PostgresBackend } = await import("../postgres-DvEPooLO.mjs");
 		const config = loadConfig();
 		if (config.storageBackend !== "postgres") return 0;
 		const pgBackend = new PostgresBackend(config.postgres ?? {});
@@ -3793,7 +3793,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-BaYX-w_d.mjs").then((n) => n.t);
+		const { serve } = await import("../daemon-VIFoKc_z.mjs").then((n) => n.t);
 		const { loadConfig: lc, ensureConfigDir } = await import("../config-BuhHWyOK.mjs").then((n) => n.r);
 		ensureConfigDir();
 		await serve(lc());

package/dist/daemon/index.mjs

@@ -7,10 +7,10 @@ import "../search-DC1qhkKn.mjs";
 import "../indexer-D53l5d1U.mjs";
 import { t as PaiClient } from "../ipc-client-CoyUHPod.mjs";
 import { i as ensureConfigDir, o as loadConfig } from "../config-BuhHWyOK.mjs";
-import "../factory-BzWfxsvK.mjs";
-import { n as serve } from "../daemon-BaYX-w_d.mjs";
+import "../factory-e0k1HWuc.mjs";
+import { n as serve } from "../daemon-VIFoKc_z.mjs";
 import "../state-C6_vqz7w.mjs";
-import "../tools-BXSwlzeH.mjs";
+import "../tools-C4SBZHga.mjs";
 import "../detector-jGBuYQJM.mjs";
 import { Command } from "commander";
 

package/dist/{daemon-BaYX-w_d.mjs → daemon-VIFoKc_z.mjs}

@@ -4,9 +4,9 @@ import { d as sha256 } from "./helpers-BEST-4Gx.mjs";
 import { n as indexAll } from "./sync-BOsnEj2-.mjs";
 import { t as configureEmbeddingModel } from "./embeddings-DGRAPAYb.mjs";
 import { n as CONFIG_FILE, s as DEFAULT_NOTIFICATION_CONFIG, t as CONFIG_DIR } from "./config-BuhHWyOK.mjs";
-import { t as createStorageBackend } from "./factory-BzWfxsvK.mjs";
+import { t as createStorageBackend } from "./factory-e0k1HWuc.mjs";
 import { C as setStorageBackend, E as startTime, O as storageBackend, S as setStartTime, T as shutdownRequested, _ as setLastIndexTime, a as indexSchedulerTimer, b as setRegistryDb, c as lastVaultIndexTime, d as setDaemonConfig, f as setEmbedInProgress, g as setLastEmbedTime, h as setIndexSchedulerTimer, i as indexInProgress, k as vaultIndexInProgress, l as notificationConfig, m as setIndexInProgress, n as embedInProgress, o as lastEmbedTime, p as setEmbedSchedulerTimer, r as embedSchedulerTimer, s as lastIndexTime, t as daemonConfig, u as registryDb, v as setLastVaultIndexTime, w as setVaultIndexInProgress, x as setShutdownRequested, y as setNotificationConfig } from "./state-C6_vqz7w.mjs";
-import { a as toolProjectDetect, c as toolProjectList, d as toolMemorySearch, i as toolSessionRoute, l as toolProjectTodo, n as toolRegistrySearch, o as toolProjectHealth, r as toolSessionList, s as toolProjectInfo, u as toolMemoryGet } from "./tools-BXSwlzeH.mjs";
+import { a as toolSessionList, c as toolProjectHealth, d as toolProjectTodo, f as toolMemoryGet, i as toolRegistrySearch, l as toolProjectInfo, n as toolMemoryTaxonomy, o as toolSessionRoute, p as toolMemorySearch, r as toolMemoryWakeup, s as toolProjectDetect, u as toolProjectList } from "./tools-C4SBZHga.mjs";
 import { t as detectTopicShift } from "./detector-jGBuYQJM.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, setPriority } from "node:os";
@@ -690,6 +690,8 @@ async function dispatchTool(method, params) {
 		case "project_detect": return toolProjectDetect(registryDb, p);
 		case "project_health": return toolProjectHealth(registryDb, p);
 		case "project_todo": return toolProjectTodo(registryDb, p);
+		case "memory_wakeup": return toolMemoryWakeup(registryDb, p);
+		case "memory_taxonomy": return toolMemoryTaxonomy(registryDb, storageBackend, p);
 		case "topic_check": return detectTopicShift(registryDb, storageBackend, p);
 		case "session_auto_route": return toolSessionRoute(registryDb, storageBackend, p);
 		case "zettel_explore":
@@ -700,7 +702,7 @@ async function dispatchTool(method, params) {
 		case "zettel_themes":
 		case "zettel_god_notes":
 		case "zettel_communities": {
-			const { toolZettelExplore, toolZettelHealth, toolZettelSurprise, toolZettelSuggest, toolZettelConverse, toolZettelThemes, toolZettelGodNotes, toolZettelCommunities } = await import("./tools-BXSwlzeH.mjs").then((n) => n.t);
+			const { toolZettelExplore, toolZettelHealth, toolZettelSurprise, toolZettelSuggest, toolZettelConverse, toolZettelThemes, toolZettelGodNotes, toolZettelCommunities } = await import("./tools-C4SBZHga.mjs").then((n) => n.t);
 			switch (method) {
 				case "zettel_explore": return toolZettelExplore(storageBackend, p);
 				case "zettel_health": return toolZettelHealth(storageBackend, p);
@@ -738,6 +740,25 @@ async function dispatchTool(method, params) {
 			if (!daemonConfig.vaultPath) throw new Error("idea_materialize requires vaultPath to be configured in the daemon config");
 			return handleIdeaMaterialize(p, daemonConfig.vaultPath);
 		}
+		case "kg_add":
+		case "kg_query":
+		case "kg_invalidate":
+		case "kg_contradictions": {
+			const { toolKgAdd, toolKgQuery, toolKgInvalidate, toolKgContradictions } = await import("./tools-C4SBZHga.mjs").then((n) => n.t);
+			const pgPool = storageBackend.getPool?.() ?? null;
+			if (!pgPool) throw new Error(`${method} requires a Postgres storage backend`);
+			switch (method) {
+				case "kg_add": return toolKgAdd(pgPool, p);
+				case "kg_query": return toolKgQuery(pgPool, p);
+				case "kg_invalidate": return toolKgInvalidate(pgPool, p);
+				case "kg_contradictions": return toolKgContradictions(pgPool, p);
+			}
+			break;
+		}
+		case "memory_tunnels": {
+			const { toolMemoryTunnels } = await import("./tools-C4SBZHga.mjs").then((n) => n.t);
+			return toolMemoryTunnels(registryDb, storageBackend, p);
+		}
 		default: throw new Error(`Unknown method: ${method}`);
 	}
 }
@@ -3062,4 +3083,4 @@ var daemon_exports = /* @__PURE__ */ __exportAll({ serve: () => serve });
 
 //#endregion
 export { serve as n, daemon_exports as t };
-//# sourceMappingURL=daemon-BaYX-w_d.mjs.map
+//# sourceMappingURL=daemon-VIFoKc_z.mjs.map