feat: add facts/knowledge notes memory class alongside instincts (#68)

Closes #65

## Summary

- Introduces **facts** — a second memory class for declarative knowledge
that doesn't fit the trigger→action instinct model (e.g. "The test DB
port is 3306", "Use `pnpm build:fast` to compile")
- Facts are **user-driven**: created in-session via four new LLM tools
(`fact_write`, `fact_read`, `fact_list`, `fact_delete`) — the user says
"remember that X" and Pi stores it directly
- The background analyzer does **not** detect facts from observations;
it only runs decay and cleanup passes on them (keeping the design simple
and reliable)
- Facts are injected into the system prompt as a `## Project Knowledge`
block after the instincts block, using the remaining char budget

## New files

| File | Purpose |
|---|---|
| `src/fact-parser.ts` | Parse/serialize fact `.md` files (YAML
frontmatter + body); mirrors `instinct-parser.ts` without
`trigger`/`action`/`graduated_to` |
| `src/fact-store.ts` | CRUD with 5s mtime-based cache; mirrors
`instinct-store.ts` |
| `src/fact-decay.ts` | Passive confidence decay (−0.05/week); reuses
`applyPassiveDecay` from `confidence.ts` |
| `src/fact-cleanup.ts` | Flagged removal, zero-confirmation TTL, hard
cap; no contradiction detection |
| `src/fact-tools.ts` | Registers `fact_write`, `fact_read`,
`fact_list`, `fact_delete` LLM tools |
| `src/*.test.ts` | Tests for all new modules (834 tests total, all
passing) |

## Modified files

- **`types.ts`** — `Fact` interface + `FactScope`/`FactSource`; three
new `Config` fields
- **`storage.ts`** — `getProjectFactsDir`/`getGlobalFactsDir` helpers;
`ensureStorageLayout` creates `facts/personal` dirs
- **`instinct-injector.ts`** — `buildFactsInjectionBlock` + `## Project
Knowledge` block appended after instincts
- **`instinct-status.ts`** — `/instinct-status` now shows a `Facts /
Knowledge Notes` section
- **`cli/analyze.ts`** — `runFactCleanupPass` + `runFactDecayPass` wired
into both analysis and consolidation passes
- **`index.ts`** — `registerAllFactTools` called in `session_start`
- **`README.md`** — Facts feature section, injection example, tool
table, config table, storage layout

## Test plan

- [ ] `npm run check -w packages/pi-continuous-learning` passes (834
tests, lint, typecheck)
- [ ] Tell Pi "remember that the test DB port is 3306" — verify Pi calls
`fact_write` and the file appears in
`~/.pi/continuous-learning/projects/<hash>/facts/personal/`
- [ ] Run `/instinct-status` — verify a `Facts / Knowledge Notes`
section appears
- [ ] Run `pi-cl-analyze` — verify it completes without error
(decay/cleanup pass runs on empty facts dirs)
- [ ] Ask Pi "what facts do I have?" — verify it calls `fact_list`

Author: MattDevy

packages/pi-continuous-learning/README.md

@@ -80,6 +80,10 @@ Before each agent turn, the injector loads instincts relevant to the current pro
 ## Learned Behaviours (Instincts)
 - [0.75] when modifying code files: Always search with grep to find relevant context before editing
 - [0.68] when debugging errors: Read stack traces to understand root cause before suggesting fixes
+
+## Project Knowledge
+- [0.80] The test database runs on port 3306
+- [0.72] Use pnpm build:fast for incremental TypeScript compilation
 ```
 
 ### 4. Feedback loop
@@ -159,6 +163,22 @@ Before creating or updating instincts, a deterministic (no LLM cost) contradicti
 
 Every write is checked against existing instincts using Jaccard similarity. If any existing instinct scores >= 0.6 similarity, the write is blocked and the LLM is instructed to update the existing one instead. This keeps the corpus clean without human effort.
 
+### Facts / Knowledge Notes
+
+Alongside behavioural instincts, the extension maintains a second memory class: **facts**. A fact is a declarative statement with no trigger or action — just something that is true.
+
+```
+Instinct: when modifying API routes → always update the OpenAPI spec
+Fact:     The staging environment lives at staging.example.com
+```
+
+Facts are **user-driven** — you create them by telling Pi to remember something during a session. Pi then calls the `fact_write` tool directly:
+
+> "Remember that the test database port is 3306"
+> "Store the fact that we use pnpm build:fast for incremental TypeScript compilation"
+
+Facts are injected into the system prompt as a separate `## Project Knowledge` block after the instincts block. They participate in the same confidence and decay system as instincts — facts that aren't confirmed decay over time and are eventually pruned. The background analyzer handles this maintenance automatically; it does **not** try to detect or create facts from observations.
+
 ---
 
 ## Slash commands
@@ -185,8 +205,12 @@ The LLM can call these directly during conversation — no slash command needed:
 | `instinct_write` | Create or update an instinct |
 | `instinct_delete` | Remove an instinct by ID |
 | `instinct_merge` | Merge multiple instincts into one |
+| `fact_list` | List knowledge facts with optional scope/domain filters |
+| `fact_read` | Read a specific fact by ID |
+| `fact_write` | Create or update a knowledge fact |
+| `fact_delete` | Remove a fact by ID |
 
-Ask Pi things like _"show me my instincts"_, _"merge these two"_, or _"delete anything with low confidence"_ and it will use these tools directly.
+Ask Pi things like _"show me my instincts"_, _"merge these two"_, or _"remember that the DB port is 3306"_ and it will use these tools directly.
 
 ---
 
@@ -363,7 +387,10 @@ All defaults work out of the box. Override at `~/.pi/continuous-learning/config.
   "consolidation_min_sessions": 10,
   "max_total_instincts_per_project": 100,
   "max_total_instincts_global": 200,
-  "max_new_instincts_per_run": 10
+  "max_new_instincts_per_run": 10,
+  "max_facts_per_project": 30,
+  "max_facts_global": 50,
+  "max_new_facts_per_run": 3
 }
 ```
 
@@ -385,6 +412,9 @@ All defaults work out of the box. Override at `~/.pi/continuous-learning/config.
 | `max_total_instincts_per_project` | 100 | Hard cap; oldest low-confidence instincts are pruned first |
 | `max_total_instincts_global` | 200 | Hard cap for global instincts |
 | `max_new_instincts_per_run` | 10 | Rate limit on instinct creation per analyzer run |
+| `max_facts_per_project` | 30 | Hard cap on facts per project; lowest-confidence pruned first |
+| `max_facts_global` | 50 | Hard cap on global facts |
+| `max_new_facts_per_run` | 3 | Rate limit on fact creation per analyzer run |
 | `log_path` | `~/.pi/continuous-learning/analyzer.log` | Analyzer log file path |
 
 ---
@@ -400,11 +430,13 @@ All data stays local on your machine:
   analyze.lock                  # Present only while analyzer runs
   analyzer.log                  # Structured JSON event log
   instincts/personal/           # Global instincts
+  facts/personal/               # Global facts
   projects/<hash>/
     project.json                # Project metadata + analysis cursor
     observations.jsonl          # Current observations
     observations.archive/       # Archived (auto-purged after 30 days)
     instincts/personal/         # Project-scoped instincts
+    facts/personal/             # Project-scoped facts
 ```
 
 ---

packages/pi-continuous-learning/src/cli/analyze.ts

@@ -32,6 +32,8 @@ import { buildConsolidateUserPrompt } from "../prompts/consolidate-user.js";
 import { countObservations } from "../observations.js";
 import { runDecayPass } from "../instinct-decay.js";
 import { runCleanupPass } from "../instinct-cleanup.js";
+import { runFactDecayPass } from "../fact-decay.js";
+import { runFactCleanupPass } from "../fact-cleanup.js";
 import { tailObservationsSince } from "../prompts/analyzer-user.js";
 import { buildSingleShotSystemPrompt } from "../prompts/analyzer-system-single-shot.js";
 import { buildSingleShotUserPrompt } from "../prompts/analyzer-user-single-shot.js";
@@ -290,6 +292,8 @@ async function analyzeProject(
 
   runCleanupPass(project.id, config, baseDir);
   runDecayPass(project.id, baseDir);
+  runFactCleanupPass(project.id, config, baseDir);
+  runFactDecayPass(project.id, baseDir);
 
   // Load current instincts inline - no tool calls needed
   const projectInstincts = loadProjectInstincts(project.id, baseDir);
@@ -627,6 +631,8 @@ async function consolidateProject(
   // Run cleanup and decay before consolidation
   runCleanupPass(project.id, config, baseDir);
   runDecayPass(project.id, baseDir);
+  runFactCleanupPass(project.id, config, baseDir);
+  runFactDecayPass(project.id, baseDir);
 
   // Load all instincts
   const projectInstincts = loadProjectInstincts(project.id, baseDir);

packages/pi-continuous-learning/src/config.ts

@@ -92,6 +92,10 @@ export const DEFAULT_CONFIG: Config = {
   consolidation_min_sessions: DEFAULT_CONSOLIDATION_MIN_SESSIONS,
   recurring_prompt_min_sessions: 3,
   recurring_prompt_score_boost: 3,
+  // Facts volume control
+  max_facts_per_project: 30,
+  max_facts_global: 50,
+  max_new_facts_per_run: 3,
 };
 
 // ---------------------------------------------------------------------------
@@ -122,6 +126,9 @@ const PartialConfigSchema = Type.Partial(
     consolidation_min_sessions: Type.Number(),
     recurring_prompt_min_sessions: Type.Number(),
     recurring_prompt_score_boost: Type.Number(),
+    max_facts_per_project: Type.Number(),
+    max_facts_global: Type.Number(),
+    max_new_facts_per_run: Type.Number(),
   }),
 );
 

packages/pi-continuous-learning/src/fact-cleanup.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdtempSync, rmSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  cleanupFlaggedFacts,
+  cleanupZeroConfirmedFacts,
+  enforceFactCap,
+  runFactCleanupPass,
+} from "./fact-cleanup.js";
+import { saveFact, listFacts, invalidateFactCache } from "./fact-store.js";
+import type { Fact, Config } from "./types.js";
+import { DEFAULT_CONFIG } from "./config.js";
+
+function makeTmpDir(): string {
+  return mkdtempSync(join(tmpdir(), "pi-cl-fact-cleanup-test-"));
+}
+
+function makeFact(id: string, overrides: Partial<Fact> = {}): Fact {
+  const old = new Date(Date.now() - 60 * 24 * 60 * 60 * 1000).toISOString(); // 60 days ago
+  return {
+    id,
+    title: id,
+    content: `Fact: ${id}`,
+    confidence: 0.5,
+    domain: "workflow",
+    source: "personal",
+    scope: "project",
+    created_at: old,
+    updated_at: old,
+    observation_count: 1,
+    confirmed_count: 0,
+    contradicted_count: 0,
+    inactive_count: 0,
+    ...overrides,
+  };
+}
+
+const BASE_CONFIG: Config = {
+  ...DEFAULT_CONFIG,
+};
+
+describe("cleanupFlaggedFacts", () => {
+  let tmpDir: string;
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    invalidateFactCache();
+  });
+
+  it("deletes facts flagged_for_removal older than threshold", () => {
+    tmpDir = makeTmpDir();
+    saveFact(makeFact("flagged-old", { flagged_for_removal: true }), tmpDir);
+    const deleted = cleanupFlaggedFacts(tmpDir, 7);
+    expect(deleted).toBe(1);
+    expect(listFacts(tmpDir)).toHaveLength(0);
+  });
+
+  it("does not delete facts flagged recently (below threshold)", () => {
+    tmpDir = makeTmpDir();
+    const recentlyFlagged = makeFact("flagged-new", {
+      flagged_for_removal: true,
+      updated_at: new Date().toISOString(),
+    });
+    saveFact(recentlyFlagged, tmpDir);
+    const deleted = cleanupFlaggedFacts(tmpDir, 7);
+    expect(deleted).toBe(0);
+  });
+
+  it("does not delete unflagged facts", () => {
+    tmpDir = makeTmpDir();
+    saveFact(makeFact("normal"), tmpDir);
+    const deleted = cleanupFlaggedFacts(tmpDir, 7);
+    expect(deleted).toBe(0);
+    expect(listFacts(tmpDir)).toHaveLength(1);
+  });
+});
+
+describe("cleanupZeroConfirmedFacts", () => {
+  let tmpDir: string;
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    invalidateFactCache();
+  });
+
+  it("deletes zero-confirmed facts older than TTL", () => {
+    tmpDir = makeTmpDir();
+    saveFact(makeFact("old-unconfirmed", { confirmed_count: 0 }), tmpDir);
+    const deleted = cleanupZeroConfirmedFacts(tmpDir, 7);
+    expect(deleted).toBe(1);
+  });
+
+  it("does not delete confirmed facts even if old", () => {
+    tmpDir = makeTmpDir();
+    saveFact(makeFact("confirmed", { confirmed_count: 3 }), tmpDir);
+    const deleted = cleanupZeroConfirmedFacts(tmpDir, 7);
+    expect(deleted).toBe(0);
+  });
+
+  it("does not delete recently created zero-confirmed facts", () => {
+    tmpDir = makeTmpDir();
+    const recent = makeFact("new-fact", {
+      confirmed_count: 0,
+      created_at: new Date().toISOString(),
+    });
+    saveFact(recent, tmpDir);
+    const deleted = cleanupZeroConfirmedFacts(tmpDir, 28);
+    expect(deleted).toBe(0);
+  });
+});
+
+describe("enforceFactCap", () => {
+  let tmpDir: string;
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    invalidateFactCache();
+  });
+
+  it("deletes lowest-confidence facts when over cap", () => {
+    tmpDir = makeTmpDir();
+    saveFact(makeFact("low", { confidence: 0.2, confirmed_count: 1 }), tmpDir);
+    saveFact(makeFact("mid", { confidence: 0.5, confirmed_count: 1 }), tmpDir);
+    saveFact(makeFact("high", { confidence: 0.8, confirmed_count: 1 }), tmpDir);
+    const deleted = enforceFactCap(tmpDir, 2);
+    expect(deleted).toBe(1);
+    const remaining = listFacts(tmpDir);
+    expect(remaining).toHaveLength(2);
+    expect(remaining.find((f) => f.id === "low")).toBeUndefined();
+  });
+
+  it("does nothing when at or below cap", () => {
+    tmpDir = makeTmpDir();
+    saveFact(makeFact("a", { confirmed_count: 1 }), tmpDir);
+    saveFact(makeFact("b", { confirmed_count: 1 }), tmpDir);
+    expect(enforceFactCap(tmpDir, 2)).toBe(0);
+    expect(enforceFactCap(tmpDir, 5)).toBe(0);
+  });
+});
+
+describe("runFactCleanupPass", () => {
+  let tmpDir: string;
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    invalidateFactCache();
+  });
+
+  it("runs all cleanup rules and returns aggregated results", () => {
+    tmpDir = makeTmpDir();
+    const projectDir = join(tmpDir, "projects", "p1", "facts", "personal");
+    mkdirSync(projectDir, { recursive: true });
+    saveFact(
+      makeFact("flagged", { flagged_for_removal: true }),
+      projectDir,
+    );
+    const result = runFactCleanupPass("p1", BASE_CONFIG, tmpDir);
+    expect(result.flaggedDeleted).toBe(1);
+    expect(result.total).toBeGreaterThanOrEqual(1);
+  });
+
+  it("returns zero result when no facts exist", () => {
+    tmpDir = makeTmpDir();
+    const result = runFactCleanupPass("no-project", BASE_CONFIG, tmpDir);
+    expect(result.total).toBe(0);
+  });
+});