pi-continuous-learning 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Devy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# pi-continuous-learning
+
+A [Pi](https://github.com/nicholasgasior/pi-coding-agent) extension that observes your coding sessions and distills patterns into reusable "instincts" - atomic learned behaviors with confidence scoring, project scoping, and closed-loop feedback validation.
+
+Inspired by [everything-claude-code/continuous-learning-v2](https://github.com/nicholasb/everything-claude-code), reimplemented as a native Pi extension in TypeScript.
+
+## How It Works
+
+```
+Pi Session (extension)                     Background analyzer (standalone)
+──────────────────────                     ──────────────────────────────────
+Extension events                           Runs on a schedule (cron/launchd)
+  │                                          │
+  v                                          v
+Observation Collector                      Reads observations.jsonl per project
+  │  writes observations.jsonl               │
+  v                                          v
+System Prompt Injection                    Haiku LLM analyzes patterns,
+  │  injects high-confidence instincts       creates/updates instinct files
+  v                                          │
+Feedback Loop                              Instinct Files (.md with YAML frontmatter)
+  │  records which instincts were active
+  v
+Confirms, contradicts, or ignores injected instincts
+```
+
+**The key idea:** the extension watches what you do, learns patterns, injects relevant instincts into future sessions, then validates whether those instincts actually helped — adjusting confidence based on real outcomes rather than observation count alone.
+
+The analyzer runs as a **separate background process** (not inside your Pi session), so it never causes lag or interference. It processes all your projects in a single pass.
+
+## Installation
+
+```bash
+pi install npm:pi-continuous-learning
+```
+
+This installs the extension globally and makes the `pi-cl-analyze` CLI available on your PATH.
+
+### Requirements
+
+- [Pi](https://github.com/nicholasgasior/pi-coding-agent) >= 0.62.0
+- An active Claude subscription (the analyzer uses Haiku via your existing Pi credentials — no separate API key needed)
+- Node.js >= 18
+
+## Usage
+
+Once installed, the extension runs automatically in your Pi sessions — observing events and injecting instincts. No configuration required for the extension itself.
+
+To analyze observations and create/update instincts, you need to run the analyzer separately (see [Background Analyzer](#background-analyzer) below).
+
+### Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/instinct-status` | Show all instincts grouped by domain with confidence scores and feedback stats |
+| `/instinct-evolve` | LLM-powered analysis of instincts: suggests merges, promotions, and cleanup |
+| `/instinct-export` | Export instincts to a JSON file (filterable by scope/domain) |
+| `/instinct-import <path>` | Import instincts from a JSON file |
+| `/instinct-promote [id]` | Promote project instincts to global scope |
+| `/instinct-projects` | List all known projects and their instinct counts |
+
+### LLM Tools
+
+The extension registers tools that the LLM can use during conversation:
+
+| Tool | Description |
+|------|-------------|
+| `instinct_list` | List instincts with optional scope/domain filters |
+| `instinct_read` | Read a specific instinct by ID |
+| `instinct_write` | Create or update an instinct |
+| `instinct_delete` | Remove an instinct by ID |
+| `instinct_merge` | Merge multiple instincts into one |
+
+You can ask Pi things like "show me my instincts", "merge these two instincts", or "delete low-confidence instincts" and it will use these tools.
+
+## Background Analyzer
+
+The analyzer is a standalone CLI that processes observations across all your projects and creates/updates instincts using Haiku. It runs outside of Pi sessions for efficiency — one process handles all projects, regardless of how many Pi sessions you have open.
+
+### Running manually
+
+```bash
+pi-cl-analyze
+```
+
+The script:
+1. Iterates all projects in `~/.pi/continuous-learning/projects.json`
+2. Skips projects with no new observations since last analysis
+3. Skips projects with fewer than 20 observations (configurable)
+4. For eligible projects: runs confidence decay, then uses Haiku to analyze patterns and write instinct files
+5. Records a cursor so only new observations are processed on subsequent runs
+
+**Safety features:**
+- **Lockfile guard:** Only one instance can run at a time. Subsequent invocations exit immediately with code 0.
+- **Global timeout:** The process exits after 5 minutes regardless of progress.
+- **Stale lock detection:** If a previous run crashed, the lockfile is automatically cleaned up after 10 minutes or if the owning process is no longer alive.
+
+### Setting up a schedule (macOS)
+
+The recommended way to run the analyzer on a recurring schedule on macOS is with `launchd`, which persists across reboots and handles log rotation.
+
+#### 1. Find the binary path
+
+```bash
+which pi-cl-analyze
+```
+
+This should print something like `/opt/homebrew/bin/pi-cl-analyze`. Use this path in the plist below.
+
+#### 2. Create the plist file
+
+```bash
+cat > ~/Library/LaunchAgents/com.pi-continuous-learning.analyze.plist << EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.pi-continuous-learning.analyze</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>$(which pi-cl-analyze)</string>
+    </array>
+    <key>StartInterval</key>
+    <integer>300</integer>
+    <key>StandardOutPath</key>
+    <string>/tmp/pi-cl-analyze.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/pi-cl-analyze.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>$(echo $PATH)</string>
+    </dict>
+</dict>
+</plist>
+EOF
+```
+
+> **Note:** The `$(which pi-cl-analyze)` and `$(echo $PATH)` substitutions are evaluated when you run the `cat` command, so the plist will contain the resolved absolute paths from your current shell.
+
+#### 3. Load the schedule
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.pi-continuous-learning.analyze.plist
+```
+
+The analyzer will now run every 5 minutes (300 seconds) in the background, starting on login. It's safe for overlapping triggers — the lockfile guard ensures only one instance runs.
+
+#### 4. Verify it's running
+
+```bash
+# Check if the job is loaded
+launchctl list | grep pi-continuous-learning
+
+# View recent output
+tail -20 /tmp/pi-cl-analyze.log
+```
+
+#### Disabling the schedule
+
+```bash
+# Stop and unload (persists across reboots — the job will not restart)
+launchctl unload ~/Library/LaunchAgents/com.pi-continuous-learning.analyze.plist
+
+# Optionally remove the plist file entirely
+rm ~/Library/LaunchAgents/com.pi-continuous-learning.analyze.plist
+```
+
+#### Temporarily pausing
+
+```bash
+# Disable (keeps the plist but prevents it from running)
+launchctl unload ~/Library/LaunchAgents/com.pi-continuous-learning.analyze.plist
+
+# Re-enable later
+launchctl load ~/Library/LaunchAgents/com.pi-continuous-learning.analyze.plist
+```
+
+### Setting up a schedule (Linux/other)
+
+Use cron:
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add this line (runs every 5 minutes):
+*/5 * * * * pi-cl-analyze >> /tmp/pi-cl-analyze.log 2>&1
+```
+
+To disable, remove the line from `crontab -e`.
+
+## Example instinct file
+
+Instincts are stored as Markdown files with YAML frontmatter:
+
+```yaml
+---
+id: grep-before-edit
+title: Grep Before Edit
+trigger: "when modifying code files"
+confidence: 0.7
+domain: "workflow"
+source: "personal"
+scope: project
+project_id: "a1b2c3d4e5f6"
+project_name: "my-project"
+observation_count: 8
+confirmed_count: 5
+contradicted_count: 1
+inactive_count: 12
+---
+
+Always search with grep to find relevant context before editing files.
+```
+
+## Confidence Scoring
+
+Confidence comes from two sources:
+
+**Discovery** (initial, based on observation count):
+- 1-2 observations: 0.3 (tentative)
+- 3-5: 0.5 (moderate)
+- 6-10: 0.7 (strong)
+- 11+: 0.85 (very strong)
+
+**Feedback** (ongoing, based on real outcomes):
+- Confirmed (behavior aligned with instinct): +0.05
+- Contradicted (behavior went against instinct): -0.15
+- Inactive (instinct irrelevant to the turn): no change
+- Passive decay: -0.02 per week without observations
+- Range: 0.1 min, 0.9 max. Below 0.1 = flagged for removal.
+
+This means an instinct observed 20 times but consistently contradicted in practice will lose confidence. Frequency alone doesn't equal correctness.
+
+## Updating
+
+```bash
+pi install npm:pi-continuous-learning
+```
+
+Your observations, instincts, and configuration are stored separately in `~/.pi/continuous-learning/` and are preserved across updates.
+
+If you have a launchd schedule set up, no changes needed — the plist points to the binary which npm updates in place.
+
+## Configuration
+
+Optional. Defaults work out of the box. Override at `~/.pi/continuous-learning/config.json`:
+
+```json
+{
+  "run_interval_minutes": 5,
+  "min_observations_to_analyze": 20,
+  "min_confidence": 0.5,
+  "max_instincts": 20,
+  "max_injection_chars": 4000,
+  "model": "claude-haiku-4-5",
+  "timeout_seconds": 120,
+  "active_hours_start": 8,
+  "active_hours_end": 23,
+  "max_idle_seconds": 1800
+}
+```
+
+Only include the fields you want to change — missing fields use the defaults above.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `min_observations_to_analyze` | 20 | Minimum observations before analysis triggers |
+| `min_confidence` | 0.5 | Instincts below this are not injected into prompts |
+| `max_instincts` | 20 | Maximum instincts injected per turn |
+| `max_injection_chars` | 4000 | Character budget for the injection block (~1000 tokens) |
+| `model` | `claude-haiku-4-5` | Model for the background analyzer |
+| `timeout_seconds` | 120 | Per-project timeout for the analyzer LLM session |
+
+## Storage
+
+All data stays local on your machine:
+
+```
+~/.pi/continuous-learning/
+  config.json                   # Optional overrides
+  projects.json                 # Project registry
+  analyze.lock                  # Lockfile (present only while analyzer runs)
+  instincts/personal/           # Global instincts
+  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
+```
+
+## Privacy & Security
+
+- All data stays on your machine — no external telemetry
+- Secrets (API keys, tokens, passwords) are scrubbed from observations before writing to disk
+- Only instincts (patterns) can be exported — never raw observations
+- The analyzer reuses your existing Pi/Claude subscription credentials
+- No separate API key required
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+
+# Type check
+npm run typecheck
+
+# Build (compiles to dist/)
+npm run build
+
+# All checks
+npm run check
+```
+
+## License
+
+MIT

package/dist/active-instincts.d.ts

@@ -0,0 +1,4 @@
+export declare function getCurrentActiveInstincts(): string[];
+export declare function setCurrentActiveInstincts(ids: string[]): void;
+export declare function clearActiveInstincts(): void;
+//# sourceMappingURL=active-instincts.d.ts.map

package/dist/active-instincts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-instincts.d.ts","sourceRoot":"","sources":["../src/active-instincts.ts"],"names":[],"mappings":"AAEA,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAEpD;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAE7D;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/active-instincts.js

@@ -0,0 +1,11 @@
+let activeInstincts = [];
+export function getCurrentActiveInstincts() {
+    return [...activeInstincts];
+}
+export function setCurrentActiveInstincts(ids) {
+    activeInstincts = [...ids];
+}
+export function clearActiveInstincts() {
+    activeInstincts = [];
+}
+//# sourceMappingURL=active-instincts.js.map

package/dist/active-instincts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-instincts.js","sourceRoot":"","sources":["../src/active-instincts.ts"],"names":[],"mappings":"AAAA,IAAI,eAAe,GAAa,EAAE,CAAC;AAEnC,MAAM,UAAU,yBAAyB;IACvC,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,GAAa;IACrD,eAAe,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,eAAe,GAAG,EAAE,CAAC;AACvB,CAAC"}

package/dist/agents-md.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Utility for reading AGENTS.md files.
+ * Provides a safe wrapper around filesystem access that returns null on any failure.
+ */
+/**
+ * Reads an AGENTS.md file and returns its content.
+ * Returns null if the file does not exist or cannot be read.
+ *
+ * @param filePath - Absolute path to the AGENTS.md file
+ */
+export declare function readAgentsMd(filePath: string): string | null;
+//# sourceMappingURL=agents-md.d.ts.map

package/dist/agents-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.d.ts","sourceRoot":"","sources":["../src/agents-md.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS5D"}

package/dist/agents-md.js

@@ -0,0 +1,23 @@
+/**
+ * Utility for reading AGENTS.md files.
+ * Provides a safe wrapper around filesystem access that returns null on any failure.
+ */
+import { existsSync, readFileSync } from "node:fs";
+/**
+ * Reads an AGENTS.md file and returns its content.
+ * Returns null if the file does not exist or cannot be read.
+ *
+ * @param filePath - Absolute path to the AGENTS.md file
+ */
+export function readAgentsMd(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=agents-md.js.map

package/dist/agents-md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../src/agents-md.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/cli/analyze-prompt.d.ts

@@ -0,0 +1,2 @@
+export declare function buildAnalyzerSystemPrompt(): string;
+//# sourceMappingURL=analyze-prompt.d.ts.map

package/dist/cli/analyze-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-prompt.d.ts","sourceRoot":"","sources":["../../src/cli/analyze-prompt.ts"],"names":[],"mappings":"AAAA,wBAAgB,yBAAyB,IAAI,MAAM,CAsElD"}

package/dist/cli/analyze-prompt.js

@@ -0,0 +1,72 @@
+export function buildAnalyzerSystemPrompt() {
+    return `You are a coding behavior analyst. Your job is to read session observations
+and produce or update instinct files that capture reusable coding patterns.
+
+Use the instinct_read tool to examine existing instincts and the instinct_write tool
+to create or update instincts based on patterns you discover.
+
+## Pattern Detection Heuristics
+
+Analyze observations for these categories:
+
+### User Corrections
+- User rephrases a request after an agent response
+- User explicitly rejects an approach
+- Trigger: the corrected behavior; Action: the preferred approach
+
+### Error Resolutions
+- Tool call returns is_error: true followed by a successful retry
+- Trigger: the error condition; Action: the proven resolution
+
+### Repeated Workflows
+- Same sequence of tool calls appears 3+ times
+- Trigger: the workflow start condition; Action: the efficient path
+
+### Tool Preferences
+- Agent consistently uses one tool over alternatives
+- Trigger: the task type; Action: the preferred tool and parameters
+
+### Anti-Patterns
+- Actions that consistently lead to errors or user corrections
+- Trigger: the bad pattern situation; Action: what to do instead
+
+## Feedback Analysis
+
+Each observation may include an active_instincts field listing instinct IDs
+that were injected into the agent's system prompt before that turn.
+
+Use this to update existing instinct confidence scores:
+- Confirmed (+0.05): instinct was active and agent followed the guidance without correction
+- Contradicted (-0.15): instinct was active but user corrected the agent
+- Inactive (no change): instinct was injected but trigger never arose
+
+When updating, increment the corresponding count field and recalculate confidence.
+
+## Confidence Scoring Rules
+
+### Initial Confidence (new instincts)
+- 1-2 observations  -> 0.3
+- 3-5 observations  -> 0.5
+- 6-10 observations -> 0.7
+- 11+ observations  -> 0.85
+
+### Clamping
+- Always clamp to [0.1, 0.9]
+
+## Scope Decision Guide
+
+Use project scope when the pattern is specific to this project's tech stack or conventions.
+Use global scope when the pattern applies universally to any coding session.
+When in doubt, prefer project scope.
+
+## Conservativeness Rules
+
+1. Only create a new instinct with 3+ clear independent observations supporting the pattern.
+2. No code snippets in the action field - plain language only.
+3. Each instinct must have one well-defined trigger.
+4. New instincts from observation data alone are capped at 0.85 confidence.
+5. Before creating, use instinct_list to check for duplicates. Update existing instincts instead.
+6. Write actions as clear instructions starting with a verb.
+7. Be skeptical of outliers - patterns seen only in unusual circumstances should not become instincts.`;
+}
+//# sourceMappingURL=analyze-prompt.js.map

package/dist/cli/analyze-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-prompt.js","sourceRoot":"","sources":["../../src/cli/analyze-prompt.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,yBAAyB;IACvC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uGAoE8F,CAAC;AACxG,CAAC"}

package/dist/cli/analyze.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=analyze.d.ts.map

package/dist/cli/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/cli/analyze.ts"],"names":[],"mappings":""}