{"_id":"@akubly/cairn","_rev":"2-813fba8eedfee98af408afcd513eee15","name":"@akubly/cairn","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@akubly/cairn","version":"0.1.0","keywords":["cairn","agentic","copilot","copilot-plugin","mcp","model-context-protocol","software-engineering","cli"],"author":{"name":"akubly"},"license":"MIT","_id":"@akubly/cairn@0.1.0","maintainers":[{"name":"akubly","email":"akubly@outlook.com"}],"homepage":"https://github.com/akubly/stunning-adventure#readme","bugs":{"url":"https://github.com/akubly/stunning-adventure/issues"},"bin":{"cairn":"dist/cli.js","cairn-mcp":"dist/mcp/server.js"},"dist":{"shasum":"538bf45c26ae8fc1f09e44d4ea0cc6d9a11e6e04","tarball":"https://registry.npmjs.org/@akubly/cairn/-/cairn-0.1.0.tgz","fileCount":68,"integrity":"sha512-s6t0+ytNYFXNEegINNAwvw3F0OfSweqLgjwF1D1WB13fb3wCwxdVQXzB5UHSaC/4BHrewOPM5tVGxnt9P3GjQA==","signatures":[{"sig":"MEYCIQCbDQr9LULC4NpptkdfDZENdiTvZDB0+0M9wo4EchIytQIhANik4NWRQ8oh78pn/SIV6Mv3hOSEy8DJepfLAkVjxnaU","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":93388},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"08813a7404d0e24c3dabdc6e7a1e656d4b712d52","scripts":{"mcp":"node dist/mcp/server.js","lint":"eslint src/","test":"vitest run","build":"tsc","clean":"rimraf dist coverage","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm run test && npm run lint"},"_npmUser":{"name":"akubly","email":"akubly@outlook.com"},"repository":{"url":"git+https://github.com/akubly/stunning-adventure.git","type":"git"},"_npmVersion":"11.3.0","description":"Cairn — an agentic software engineering platform. Built stone by stone. Showing the way.","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^4.3.6","better-sqlite3":"^12.8.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","eslint":"^10.1.0","rimraf":"^6.1.3","vitest":"^4.1.2","prettier":"^3.8.1","@eslint/js":"^10.0.1","typescript":"^5.9.3","@types/node":"^25.5.0","typescript-eslint":"^8.57.2","@types/better-sqlite3":"^7.6.13","@typescript-eslint/parser":"^8.57.2","@typescript-eslint/eslint-plugin":"^8.57.2"},"_npmOperationalInternal":{"tmp":"tmp/cairn_0.1.0_1775368482845_0.7092437835715488","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@akubly/cairn","version":"0.2.0","description":"Cairn — an agentic software engineering platform. Built stone by stone. Showing the way.","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"cairn":"dist/cli.js","cairn-mcp":"dist/mcp/server.js"},"scripts":{"build":"tsc","test":"vitest run","lint":"eslint src/","clean":"rimraf dist coverage","typecheck":"tsc --noEmit","mcp":"node dist/mcp/server.js","prepublishOnly":"npm run build && npm run test && npm run lint"},"engines":{"node":">=20.0.0"},"license":"MIT","author":{"name":"akubly"},"repository":{"type":"git","url":"git+https://github.com/akubly/stunning-adventure.git"},"homepage":"https://github.com/akubly/stunning-adventure#readme","keywords":["cairn","agentic","copilot","copilot-plugin","mcp","model-context-protocol","software-engineering","cli"],"devDependencies":{"@eslint/js":"^10.0.1","@types/better-sqlite3":"^7.6.13","@types/node":"^25.5.0","@typescript-eslint/eslint-plugin":"^8.57.2","@typescript-eslint/parser":"^8.57.2","eslint":"^10.1.0","prettier":"^3.8.1","rimraf":"^6.1.3","tsx":"^4.21.0","typescript":"^5.9.3","typescript-eslint":"^8.57.2","vitest":"^4.1.2"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","better-sqlite3":"^12.8.0","zod":"^4.3.6"},"_id":"@akubly/cairn@0.2.0","gitHead":"236aeae0cf06775cdccfff7c85a5bd704f7b7d4e","bugs":{"url":"https://github.com/akubly/stunning-adventure/issues"},"_nodeVersion":"22.22.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-xpcScf6BcfqXOWHJtlHUC2ZJIMj5DvZdznyOoj7utzjCFP1f2/HX12jPwTOppUgpxUNBbCnjnV+kwIXSuzB6oQ==","shasum":"504d6a8f00ac89a1beeee127a21b961fd8186d15","tarball":"https://registry.npmjs.org/@akubly/cairn/-/cairn-0.2.0.tgz","fileCount":92,"unpackedSize":220799,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEg+zg1Vw0hp8vVU14aK0BC99hMmWUmMgZJCg5S/SmpoAiB2ggEKEFxabzt2Lm984bA7RVzjrOratemCmkjFT2BjvQ=="}]},"_npmUser":{"name":"akubly","email":"akubly@outlook.com"},"directories":{},"maintainers":[{"name":"akubly","email":"akubly@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cairn_0.2.0_1776126486548_0.8781988338774909"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-05T05:54:42.735Z","modified":"2026-04-14T00:28:06.813Z","0.1.0":"2026-04-05T05:54:43.005Z","0.2.0":"2026-04-14T00:28:06.701Z"},"bugs":{"url":"https://github.com/akubly/stunning-adventure/issues"},"author":{"name":"akubly"},"license":"MIT","homepage":"https://github.com/akubly/stunning-adventure#readme","keywords":["cairn","agentic","copilot","copilot-plugin","mcp","model-context-protocol","software-engineering","cli"],"repository":{"type":"git","url":"git+https://github.com/akubly/stunning-adventure.git"},"description":"Cairn — an agentic software engineering platform. Built stone by stone. Showing the way.","maintainers":[{"name":"akubly","email":"akubly@outlook.com"}],"readme":"# 🪨 Cairn\r\n\r\n> Built stone by stone. Showing the way.\r\n\r\nAn agentic software engineering platform that serves as a mirror — reflecting your engineering practice back to you with honest, actionable clarity.\r\n\r\n## Philosophy\r\n\r\n1. **Honest about human limitations** — fatigue, impatience, rubber-stamping. Not shameful. Just real.\r\n2. **Self-reflection as a feature** — shows you your own patterns, not to judge, but to inform.\r\n3. **Growth is the metric** — not velocity, not coverage, not throughput. *Are you getting better?*\r\n4. **Agents as individuals** — natural language, persistent memory, evolving relationships.\r\n\r\n## What's Built\r\n\r\nCairn stores all data in `~/.cairn/knowledge.db` (SQLite, WAL mode). Three agents, a hook system, and an MCP server operate on that shared knowledge base:\r\n\r\n### Archivist — *records what happened*\r\n\r\nSession recording, event logging, and queryable session state.\r\n\r\n- **Session lifecycle** — start, resume, stop, crash recovery\r\n- **Event recording** — tool use, errors, guardrail skips — all secret-scrubbed (9 pattern categories)\r\n- **Queryable state** — session summaries, event search, \"has X occurred?\" checks\r\n\r\n### Curator — *finds what it means*\r\n\r\nProcesses the event stream to detect patterns and generate insights.\r\n\r\n- **Cursor-based processing** — idempotent, crash-safe (transactional), processes only new events\r\n- **Recurring error detection** — groups errors by category+message, surfaces patterns at threshold\r\n- **Error sequence detection** — finds `event → error` temporal correlations within sessions\r\n- **Skip frequency detection** — identifies habitually bypassed guardrails\r\n- **Static prescriptions** — actionable advice by error category (build, test, type, lint, auth)\r\n- **Insight lifecycle** — active → stale → pruned, with evidence tracking and reinforcement\r\n\r\n### Prescriber — *closes the feedback loop*\r\n\r\nTransforms Curator insights into concrete, prioritized improvement suggestions. Closes the observe→analyze→act loop.\r\n\r\n- **Prescription generation** — templates per pattern type (recurring error, error sequence, skip frequency)\r\n- **Priority scoring** — currently confidence-based, so higher-confidence patterns are surfaced first\r\n- **8-state lifecycle** — generated → accepted → applied (or rejected/deferred/expired/suppressed/failed)\r\n- **Human-in-the-loop** — prescriptions require explicit acceptance before the Apply Engine writes anything\r\n- **Apply Engine** — writes sidecar `.instructions.md` files with rollback support and drift detection\r\n- **Auto-suppression** — prescriptions are suppressed automatically after repeated deferrals reach a configurable threshold; duplicates are prevented by idempotency checks\r\n- **Session-aware deferral** — deferred prescriptions resurface after a configurable number of sessions until they are accepted, rejected, or auto-suppressed\r\n\r\n### Hooks — *connects to Copilot CLI*\r\n\r\nCopilot CLI hooks wire Cairn into every tool call, fail-open so they never break your workflow. Hooks are packaged as a Copilot CLI plugin (`.github/plugin/hooks.json`) and also available as PowerShell wrappers (`.github/hooks/cairn/*.ps1`).\r\n\r\n- **`preToolUse`** — session catch-up and crash recovery. On first tool call, recovers any orphaned session, runs curation, and chains the Prescriber when insights change. On subsequent calls, exits immediately (fast path).\r\n- **`postToolUse`** — event recording. Reads the hook payload from stdin, logs tool use or errors to the active session via the Archivist.\r\n\r\n### MCP Server — *speaks to conversations*\r\n\r\nTen tools expose Cairn's knowledge base to Copilot conversations. Tool names follow a verb–noun convention (`get_status`, not `status_get`) so agents can infer behavior from the name alone.\r\n\r\n| Tool | What it answers |\r\n|------|----------------|\r\n| `get_status` | What is Cairn tracking right now? (active session + curator health) |\r\n| `list_insights` | What patterns has the curator found? (filterable by status) |\r\n| `get_session` | What happened in a specific session? (events, errors, skips) |\r\n| `search_events` | Find events by type pattern within a session |\r\n| `run_curate` | Trigger the curator to process new events and discover patterns |\r\n| `check_event` | Has a specific event type occurred? (boolean) |\r\n| `list_prescriptions` | What improvement suggestions are available? (filterable by status) |\r\n| `get_prescription` | Full detail on a specific suggestion — rationale, proposed change, diff preview |\r\n| `resolve_prescription` | Accept, reject, or defer a suggestion |\r\n| `show_growth` | How have patterns been resolved over time? (trends + stats) |\r\n\r\n### Knowledge Store\r\n\r\n| Table | Purpose |\r\n|-------|---------|\r\n| `sessions` | Session lifecycle tracking |\r\n| `event_log` | Immutable event stream |\r\n| `insights` | Pattern-based discoveries with evidence and prescriptions |\r\n| `prescriptions` | Improvement suggestions with 8-state lifecycle |\r\n| `managed_artifacts` | Files written by the Apply Engine (checksums + rollback) |\r\n| `errors` | Error records for RCA |\r\n| `preferences` | Cascading settings (session → user → system) |\r\n| `skip_breadcrumbs` | Intentional guardrail skip tracking |\r\n| `curator_state` | Processing cursor (singleton) |\r\n| `prescriber_state` | Prescriber counters (`sessions_since_install`, `pending_count`) |\r\n| `topology_cache` | Artifact discovery scan results |\r\n\r\n## Installation\r\n\r\n**As a library:**\r\n\r\n```bash\r\nnpm install @akubly/cairn\r\n```\r\n\r\n**As a Copilot CLI plugin** (hooks + MCP server, no manual wiring):\r\n\r\nClone this repo and point your Copilot CLI at it. The manifests in `.github/plugin/` configure hooks and the MCP server automatically.\r\n\r\n## Usage\r\n\r\nCairn is a TypeScript library (`@akubly/cairn`). Import and use programmatically:\r\n\r\n```typescript\r\nimport {\r\n  startArchivistSession,\r\n  recordToolUse,\r\n  recordError,\r\n  curate,\r\n  getCuratorStatus,\r\n  getInsights,\r\n} from '@akubly/cairn';\r\n\r\n// Record\r\nconst sessionId = startArchivistSession('org/repo', 'main');\r\nrecordToolUse(sessionId, 'grep', { pattern: 'TODO' });\r\nrecordError(sessionId, 'build', 'TS2345: Type mismatch');\r\n\r\n// Analyze\r\nconst result = curate(); // → { eventsProcessed, insightsCreated, insightsReinforced }\r\nconst status = getCuratorStatus();\r\nconst insights = getInsights('active');\r\n```\r\n\r\n## Development\r\n\r\n```bash\r\nnpm install\r\nnpm run build     # TypeScript → dist/\r\nnpm test          # 136 tests across 6 files (vitest)\r\nnpm run lint      # ESLint\r\nnpm run typecheck # tsc --noEmit\r\nnpm run mcp       # Start the MCP server (requires build first)\r\n```\r\n\r\n## Plugin Packaging\r\n\r\nCairn supports two MCP setup paths:\r\n\r\n1. **Plugin** (recommended) — the manifests in `.github/plugin/` (including `.mcp.json`) declare hooks, the MCP server, and metadata. The Copilot CLI wires everything automatically on install. No additional config needed.\r\n\r\n2. **Manual MCP registration** — if not using the plugin flow, register Cairn's MCP server directly via `.copilot/mcp-config.json` (repo-scoped, checked in) or `~/.copilot/mcp-config.json` (user-scoped, personal overrides).\r\n\r\n## Roadmap\r\n\r\n| Phase | What | Status |\r\n|-------|------|--------|\r\n| 0–1a | Foundation + Schema | ✅ Done |\r\n| 1b–2 | Archivist + Event Infrastructure | ✅ Done |\r\n| 3 | Curator + Pattern Detection | ✅ Done |\r\n| 4 | Session Hooks + Crash Recovery | ✅ Done |\r\n| 5 | MCP Server | ✅ Done |\r\n| 6 | Plugin Packaging | ✅ Done |\r\n| 7 | Prescriber — Close the feedback loop | ✅ Done |\r\n\r\n## License\r\n\r\nMIT","readmeFilename":"README.md"}