claude-priors 0.1.0

package/bin/cli.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const PRIORS_MARKER = '## Priors';
+const VERSION = '0.1.0';
+
+// Resolve paths to bundled assets (works both locally and via npx)
+const PKG_ROOT = path.resolve(__dirname, '..');
+const SKILL_SRC = path.resolve(PKG_ROOT, '..', 'skill', 'SKILL.md');
+const BOOTSTRAP_SRC = path.resolve(PKG_ROOT, '..', 'bootstrap', 'CLAUDE.md.snippet');
+
+// Fallback: when installed as npm package, skill/ and bootstrap/ are siblings to bin/
+const SKILL_SRC_ALT = path.resolve(PKG_ROOT, 'skill', 'SKILL.md');
+const BOOTSTRAP_SRC_ALT = path.resolve(PKG_ROOT, 'bootstrap', 'CLAUDE.md.snippet');
+
+function resolveAsset(primary, fallback) {
+  if (fs.existsSync(primary)) return primary;
+  if (fs.existsSync(fallback)) return fallback;
+  return null;
+}
+
+function readAsset(primary, fallback) {
+  const resolved = resolveAsset(primary, fallback);
+  if (!resolved) {
+    console.error(`Error: Could not find asset. Looked in:\n  ${primary}\n  ${fallback}`);
+    process.exit(1);
+  }
+  return fs.readFileSync(resolved, 'utf8');
+}
+
+function printUsage() {
+  console.log(`
+claude-priors v${VERSION} — Persistent agent memory for AI coding assistants
+
+Usage:
+  claude-priors init [options]    Bootstrap priors in current directory
+  claude-priors status            Show priors stats
+  claude-priors help              Show this help
+
+Options:
+  --shared    Git-track priors (default: git-ignored)
+  --global    Install skill to ~/.claude/skills/ instead of repo
+  `);
+}
+
+function init(args) {
+  const cwd = process.cwd();
+  const shared = args.includes('--shared');
+  const global = args.includes('--global');
+
+  console.log(`\nclaude-priors v${VERSION}`);
+  console.log(`Initializing in: ${cwd}\n`);
+
+  // 1. Create .claude/priors/
+  const priorsDir = path.join(cwd, '.claude', 'priors');
+  if (!fs.existsSync(priorsDir)) {
+    fs.mkdirSync(priorsDir, { recursive: true });
+    fs.writeFileSync(path.join(priorsDir, '.gitkeep'), '');
+    console.log('  Created .claude/priors/');
+  } else {
+    console.log('  .claude/priors/ already exists');
+  }
+
+  // 2. Copy SKILL.md
+  const skillContent = readAsset(SKILL_SRC, SKILL_SRC_ALT);
+  let skillDir;
+  if (global) {
+    skillDir = path.join(
+      process.env.HOME || process.env.USERPROFILE,
+      '.claude', 'skills', 'knowledge-extraction'
+    );
+  } else {
+    skillDir = path.join(cwd, '.claude', 'skills', 'knowledge-extraction');
+  }
+
+  if (!fs.existsSync(skillDir)) {
+    fs.mkdirSync(skillDir, { recursive: true });
+  }
+
+  const skillDest = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillDest)) {
+    fs.writeFileSync(skillDest, skillContent);
+    console.log(`  Created ${global ? '~/.claude/skills' : '.claude/skills'}/knowledge-extraction/SKILL.md`);
+  } else {
+    // Check version
+    const existing = fs.readFileSync(skillDest, 'utf8');
+    if (existing === skillContent) {
+      console.log(`  SKILL.md already up to date`);
+    } else {
+      fs.writeFileSync(skillDest, skillContent);
+      console.log(`  Updated SKILL.md to v${VERSION}`);
+    }
+  }
+
+  // 3. Append bootstrap to CLAUDE.md (or AGENTS.md)
+  const bootstrapContent = readAsset(BOOTSTRAP_SRC, BOOTSTRAP_SRC_ALT);
+
+  // Detect which instruction file exists
+  let instructionFile = null;
+  const candidates = ['CLAUDE.md', 'AGENTS.md'];
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(cwd, candidate))) {
+      instructionFile = candidate;
+      break;
+    }
+  }
+
+  if (!instructionFile) {
+    instructionFile = 'CLAUDE.md';
+  }
+
+  const instructionPath = path.join(cwd, instructionFile);
+
+  if (fs.existsSync(instructionPath)) {
+    const existing = fs.readFileSync(instructionPath, 'utf8');
+    if (existing.includes(PRIORS_MARKER)) {
+      console.log(`  ${instructionFile} already has priors bootstrap`);
+    } else {
+      fs.writeFileSync(instructionPath, existing.trimEnd() + '\n\n' + bootstrapContent.trim() + '\n');
+      console.log(`  Appended priors bootstrap to ${instructionFile}`);
+    }
+  } else {
+    fs.writeFileSync(instructionPath, bootstrapContent.trim() + '\n');
+    console.log(`  Created ${instructionFile} with priors bootstrap`);
+  }
+
+  // 4. Handle .gitignore
+  const gitignorePath = path.join(cwd, '.gitignore');
+  const priorsGlob = '.claude/priors/';
+
+  if (!shared) {
+    if (fs.existsSync(gitignorePath)) {
+      const gitignore = fs.readFileSync(gitignorePath, 'utf8');
+      if (!gitignore.includes(priorsGlob)) {
+        fs.writeFileSync(gitignorePath, gitignore.trimEnd() + '\n\n# Agent priors (local knowledge)\n' + priorsGlob + '\n');
+        console.log('  Added .claude/priors/ to .gitignore');
+      } else {
+        console.log('  .gitignore already excludes priors');
+      }
+    } else {
+      fs.writeFileSync(gitignorePath, '# Agent priors (local knowledge)\n' + priorsGlob + '\n');
+      console.log('  Created .gitignore with priors exclusion');
+    }
+  } else {
+    console.log('  --shared: priors will be git-tracked');
+  }
+
+  console.log('\nDone! Your agent will now learn from every conversation.\n');
+}
+
+function status() {
+  const cwd = process.cwd();
+  const priorsDir = path.join(cwd, '.claude', 'priors');
+
+  if (!fs.existsSync(priorsDir)) {
+    console.log('No priors directory found. Run `claude-priors init` first.');
+    return;
+  }
+
+  const files = fs.readdirSync(priorsDir).filter(f => f.endsWith('.md'));
+
+  if (files.length === 0) {
+    console.log('Priors directory exists but is empty. The agent will start writing priors as it learns.\n');
+    return;
+  }
+
+  console.log(`\nPriors: ${priorsDir}\n`);
+
+  let totalEntries = 0;
+
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(priorsDir, file), 'utf8');
+
+    // Parse frontmatter
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    let topic = file.replace('.md', '');
+    let summary = '';
+    let entries = 0;
+    let lastUpdated = '';
+
+    if (fmMatch) {
+      const fm = fmMatch[1];
+      const topicMatch = fm.match(/topic:\s*(.+)/);
+      const summaryMatch = fm.match(/summary:\s*(.+)/);
+      const entriesMatch = fm.match(/entries:\s*(\d+)/);
+      const dateMatch = fm.match(/last_updated:\s*(.+)/);
+
+      if (topicMatch) topic = topicMatch[1].trim();
+      if (summaryMatch) summary = summaryMatch[1].trim();
+      if (entriesMatch) entries = parseInt(entriesMatch[1]);
+      if (dateMatch) lastUpdated = dateMatch[1].trim();
+    }
+
+    totalEntries += entries;
+    console.log(`  ${file}`);
+    console.log(`    Topic: ${topic} | Entries: ${entries} | Updated: ${lastUpdated || 'unknown'}`);
+    if (summary) console.log(`    ${summary}`);
+    console.log();
+  }
+
+  console.log(`Total: ${files.length} files, ${totalEntries} entries\n`);
+}
+
+// --- Main ---
+const args = process.argv.slice(2);
+const command = args[0];
+
+switch (command) {
+  case 'init':
+    init(args.slice(1));
+    break;
+  case 'status':
+    status();
+    break;
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    printUsage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+}

package/bootstrap/CLAUDE.md.snippet

@@ -0,0 +1,8 @@
+
+## Priors
+
+This project uses agent priors (`.claude/priors/`) — persistent knowledge the agent accumulates across sessions.
+
+**Start of every task:** List `.claude/priors/` and read each file's YAML frontmatter (`topic`, `summary`). Load full content only for files relevant to the current task.
+
+**End of every conversation** where you were corrected, discovered something unexpected, or the user provided context you couldn't derive from code: load the `knowledge-extraction` skill from `.claude/skills/` and extract priors.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "claude-priors",
+  "version": "0.1.0",
+  "description": "Persistent agent memory for AI coding assistants. One command to enable your agent to learn from every conversation.",
+  "bin": {
+    "claude-priors": "./bin/cli.js"
+  },
+  "keywords": [
+    "claude",
+    "ai",
+    "agent",
+    "memory",
+    "priors",
+    "coding-assistant",
+    "opencode",
+    "cursor",
+    "mcp"
+  ],
+  "author": "Jiahao Li",
+  "license": "MIT",
+  "homepage": "https://github.com/jiahaoli/claude-priors#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jiahaoli/claude-priors.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jiahaoli/claude-priors/issues"
+  },
+  "files": [
+    "bin/",
+    "skill/",
+    "bootstrap/"
+  ]
+}

package/skill/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: knowledge-extraction
+description: Detailed instructions for the agent priors system — how to extract, format, store, consume, and manage priors files in .claude/priors/. Load this skill when you need to write new priors, reorganize existing priors, or understand the priors file format. The always-on bootstrap lives in CLAUDE.md; this skill provides the full reference.
+---
+
+# Knowledge Extraction — Priors System Reference
+
+This skill is the detailed reference for the priors system. The always-on bootstrap in `CLAUDE.md` tells the agent to scan and use priors every session. This skill is loaded on demand when the agent needs to **write, format, or manage** priors.
+
+## Skills vs Priors
+
+- **Skills** (`.claude/skills/`) — Explicit, user-provided and user-maintained. **Never write agent-learned knowledge into these files.**
+- **Priors** (`.claude/priors/`) — Implicit, agent-learned and agent-maintained. The agent's working memory persisted to disk.
+
+## Agent Autonomy Over Priors
+
+Priors are fully agent-managed. The agent has **unconditional permission** to create, edit, rewrite, merge, split, delete, and reorganize priors files and directory structure. No user confirmation needed. Optimize purely for agent utility: fast scanning, low token cost, high signal density.
+
+## When to Extract
+
+After completing a task, extract if the conversation contained:
+
+1. **User correction** — User pointed out something wrong
+2. **Unexpected discovery** — Something behaved differently than assumed
+3. **Domain context the user provided** — System behavior, business logic, conventions not in code
+4. **Multi-step debugging** — Root cause of a back-and-forth diagnosis
+5. **Workaround or gotcha** — Non-obvious solution or edge case
+6. **User-volunteered context** — User proactively provided info (strong non-derivable signal)
+
+Do NOT extract when:
+- Task completed smoothly on first attempt
+- Knowledge already exists in skills or priors
+- Insight is too one-time-specific to reuse
+
+## Derivable vs Non-Derivable Context
+
+- **Derivable** — Discoverable from codebase (schemas, file structure). Don't persist unless expensive to re-derive.
+- **Non-derivable** — Exists only in user's head or external systems (timezone configs, business events, product behavior). Always persist.
+
+When a user volunteers information unprompted, it's almost certainly non-derivable — they're telling you because they know you can't find it. Always capture it.
+
+## Priors File Format
+
+### Frontmatter (required)
+
+Every priors file has YAML frontmatter for progressive disclosure — the agent scans frontmatter to decide relevance before loading the body.
+
+```yaml
+---
+topic: <short topic name>
+summary: <one-line description — used for relevance scanning without loading body>
+entries: <count>
+last_updated: <YYYY-MM-DD>
+---
+```
+
+### Body
+
+```markdown
+# <Topic>
+
+## <Section>
+
+### <Fact title>
+<!-- Learned: YYYY-MM-DD -->
+<1-3 sentences: fact, consequence, correct approach. Max 5 lines.>
+```
+
+### Entry rules
+
+- State the **fact**, not the discovery story
+- Include **consequence** of getting it wrong
+- Include the **correct approach**
+- Max 5 lines per entry
+- Code snippets only when they save more words than they cost
+- Newest entries first within each section
+
+## Where to Store
+
+All priors: `<repo>/.claude/priors/`. Organize by **topic domain**:
+
+```
+.claude/priors/
+├── data-analysis.md
+├── schema.md
+├── deployment.md
+└── product.md
+```
+
+Decision tree:
+1. `.claude/priors/` doesn't exist? Create it.
+2. Relevant file exists? Append. If not, create with frontmatter.
+3. Relevant `##` section exists? Append under it. If not, create one.
+4. Update frontmatter (`entries`, `last_updated`) after every edit.
+
+## Execution (Writing Priors)
+
+1. Identify extractable lessons from conversation
+2. Draft compact entries
+3. Read target priors file (or create with frontmatter)
+4. Append under appropriate section
+5. Update frontmatter
+6. Briefly confirm to user what was captured
+
+Do this automatically at conversation end without being asked.
+
+## Execution (Reading Priors)
+
+1. List `.claude/priors/`
+2. Read frontmatter only (first lines up to closing `---`)
+3. Based on `topic` and `summary`, decide relevance to current task
+4. Load full body only for relevant files
+
+## Maintenance
+
+Proactively maintain quality:
+- **Merge** overlapping files
+- **Split** files exceeding ~50 entries
+- **Rewrite** verbose or unclear entries
+- **Delete** outdated entries or entries now covered by explicit skills
+- **Update frontmatter** after every change