{"_id":"@aegntic/prologue","_rev":"2-7d02a106d11c02e313253e7e5d72b446","name":"@aegntic/prologue","dist-tags":{"latest":"1.1.1"},"versions":{"1.1.0":{"name":"@aegntic/prologue","version":"1.1.0","keywords":["ai","agent","memory","knowledge","persistence","mcp","claude"],"license":"MIT","_id":"@aegntic/prologue@1.1.0","maintainers":[{"name":"catface","email":"catface@aegntic.ai"}],"bin":{"prologue-mcp":"dist/mcp/server.js"},"dist":{"shasum":"91ed6d2bcdca774bbb3863ccc04fe55c9c2f8ba2","tarball":"https://registry.npmjs.org/@aegntic/prologue/-/prologue-1.1.0.tgz","fileCount":43,"integrity":"sha512-4dn6ZoluXGHO3JwoPp+yarP0OD9xiU6Wj4cW3DABu6MBKsy3sk7/1tje1W2ilN8UnCiKdW3KipxlLsqXMj9BnA==","signatures":[{"sig":"MEYCIQC9wVKUuqPK2XP9EKJ0Dt/w3hrXlqGFMFcoGeThtCKmkQIhAJT1zMsYLJ9H7dqMF0A6daY+M8bOAyU8sT1DoVr2fo0R","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":127094},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./fpef":{"types":"./dist/fpef/mod.d.ts","import":"./dist/fpef/mod.js"},"./obsidian":{"types":"./dist/obsidian/mod.d.ts","import":"./dist/obsidian/mod.js"},"./orchestrator":{"types":"./dist/orchestrator/mod.d.ts","import":"./dist/orchestrator/mod.js"}},"gitHead":"a5c334be923b008ebaa1bd274174c0c066c97908","scripts":{"lint":"biome check .","test":"bun test","build":"bun build ./src/index.ts --outdir ./dist --target bun --external zod && bun build ./src/orchestrator/mod.ts --outdir ./dist/orchestrator --target bun --external zod && bun build ./src/fpef/mod.ts --outdir ./dist/fpef --target bun --external zod && bun build ./src/obsidian/mod.ts --outdir ./dist/obsidian --target bun --external zod && bun build ./src/mcp/server.ts --outdir ./dist/mcp --target bun --external zod && tsc -p tsconfig.build.json","format":"biome format . --write","typecheck":"tsc --noEmit","prepublishOnly":"bun run build"},"_npmUser":{"name":"catface","email":"catface@aegntic.ai"},"_npmVersion":"11.12.1","description":"
","directories":{},"_nodeVersion":"24.14.1","dependencies":{"zod":"^4.3.6"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest","typescript":"^5.9.0"},"_npmOperationalInternal":{"tmp":"tmp/prologue_1.1.0_1775543684449_0.546181956267058","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@aegntic/prologue","version":"1.1.1","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./orchestrator":{"types":"./dist/orchestrator/mod.d.ts","import":"./dist/orchestrator/mod.js"},"./fpef":{"types":"./dist/fpef/mod.d.ts","import":"./dist/fpef/mod.js"},"./obsidian":{"types":"./dist/obsidian/mod.d.ts","import":"./dist/obsidian/mod.js"}},"bin":{"prologue-mcp":"dist/mcp/server.js"},"scripts":{"test":"bun test","typecheck":"tsc --noEmit","lint":"biome check .","format":"biome format . --write","build":"bun build ./src/index.ts --outdir ./dist --target bun --external zod && bun build ./src/orchestrator/mod.ts --outdir ./dist/orchestrator --target bun --external zod && bun build ./src/fpef/mod.ts --outdir ./dist/fpef --target bun --external zod && bun build ./src/obsidian/mod.ts --outdir ./dist/obsidian --target bun --external zod && bun build ./src/mcp/server.ts --outdir ./dist/mcp --target bun --external zod && tsc -p tsconfig.build.json","prepublishOnly":"bun run build"},"dependencies":{"zod":"^4.3.6"},"devDependencies":{"@types/bun":"latest","typescript":"^5.9.0"},"keywords":["ai","agent","memory","knowledge","persistence","mcp","claude"],"license":"MIT","gitHead":"59dcf96e51675fb62c1626f76627c0dcb4971ccc","_id":"@aegntic/prologue@1.1.1","description":"
","_nodeVersion":"24.14.1","_npmVersion":"11.12.1","dist":{"integrity":"sha512-2fR6pqk8nt/8xdAa8AVKg/FWLWjS/ZIyog5N48kLccmjNDpJxnEG07LO3MlUgFKTJzFIDoSSORERPz5aY3lSLA==","shasum":"64acbd063544f250efa687ef0ae8a187bd7e1506","tarball":"https://registry.npmjs.org/@aegntic/prologue/-/prologue-1.1.1.tgz","fileCount":43,"unpackedSize":127488,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH0NO7TJkVk3X/H588xoO/BpguiTHDBlaJ0XfqRxWcP8AiEAwh0KIwKg+Qzmem0DXzHPW8m4182LE/47N5zarcx+cZw="}]},"_npmUser":{"name":"catface","email":"catface@aegntic.ai"},"directories":{},"maintainers":[{"name":"catface","email":"catface@aegntic.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/prologue_1.1.1_1775573866179_0.8352888114888612"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-07T06:34:44.391Z","modified":"2026-04-07T14:57:46.434Z","1.1.0":"2026-04-07T06:34:44.597Z","1.1.1":"2026-04-07T14:57:46.312Z"},"license":"MIT","keywords":["ai","agent","memory","knowledge","persistence","mcp","claude"],"description":"
","maintainers":[{"name":"catface","email":"catface@aegntic.ai"}],"readme":"
\n\n```\n ████ \n ░░███ \n ████████ ████████ ██████ ░███ ██████ ███████ █████ ████ ██████ \n░░███░░███░░███░░███ ███░░███ ░███ ███░░███ ███░░███░░███ ░███ ███░░███\n ░███ ░███ ░███ ░░░ ░███ ░███ ░███ ░███ ░███░███ ░███ ░███ ░███ ░███████ \n ░███ ░███ ░███ ░███ ░███ ░███ ░███ ░███░███ ░███ ░███ ░███ ░███░░░ \n ░███████ █████ ░░██████ █████░░██████ ░░███████ ░░████████░░██████ \n ░███░░░ ░░░░░ ░░░░░░ ░░░░░ ░░░░░░ ░░░░░███ ░░░░░░░░ ░░░░░░ \n ░███ ███ ░███ \n █████ ░░██████ \n░░░░░ ░░░░░░ \n```\n\n### AI Agent Memory Library\n\n**Dual-layer memory. First-principles execution. Zero compromise.**\n\n*Long-term persistence for AI agents — file-based storage with optional\nknowledge graph, compression ladders, visibility boundaries, and\nbuilt-in safety frameworks.*\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Bun](https://img.shields.io/badge/runtime-bun-6e2bff.svg)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/typescript-strict-3178c6.svg)](https://typescriptlang.org)\n[![Tests](https://img.shields.io/badge/tests-148%20pass-brightgreen.svg)]()\n\n---\n\n

\n Built by aegntic.ai — R&D division of ae.ltd\n

\n\n
\n\n---\n\n## What is Prologue?\n\nPrologue gives AI agents a **durable memory system** that survives context window resets, session restarts, and process crashes. It's not a vector database wrapper — it's a purpose-built memory architecture with three integrated products:\n\n| Product | Purpose |\n|---------|---------|\n| **MemoryMatrix** | Core memory store — file-based persistence with optional Graphiti knowledge graph. Compression ladders (working → project → overview → core). Visibility boundaries (private → inspectable → shared → canonical). Atomic writes. |\n| **Orchestrator** | Task orchestration — spawns agent CLIs, monitors execution, runs post-session analysis (git diff → insight extraction → automatic memory storage). Built-in recovery manager with graduated escalation. |\n| **FPEF v2.0** | First Principles Execution Framework — 4-phase gate enforcement (Find → Prove → Evidence → Fix). Post-hoc output validation. Anti-dishonesty safeguards. Catastrophic failure recovery protocol. |\n\n## Quick Start\n\n```bash\n# Install\nbun add prologue\n\n# Or clone for development\ngit clone https://github.com/aegntic/prologue.git && cd prologue && bun install\n```\n\n```typescript\nimport { MemoryMatrix } from \"prologue\";\n\n// Create a memory store for your project\nconst memory = await MemoryMatrix.create(\"/path/to/project\");\n\n// Store a memory\nconst cell = await memory.store(\"Auth system uses JWT with RS256 signing\", {\n visibility: \"private\",\n compression: \"working\",\n tags: [\"auth\", \"jwt\"],\n});\nconsole.log(cell.envelope.id); // \"a1b2c3d4-...\"\n\n// Query memories\nconst results = await memory.query(\"auth token\");\nconsole.log(results[0].cell.body.content); // \"Auth system uses JWT...\"\n\n// Promote to durable storage\nawait memory.promote(cell.envelope.id, \"project\");\n\n// Scan envelopes (no body data — visibility-respecting)\nconst envelopes = await memory.envelopeScan(\"shared\");\n```\n\n## Architecture\n\n### Memory Compression Ladder\n\nMemories move up through four compression levels as confidence grows:\n\n```\n WORKING PROJECT OVERVIEW CORE\n (scratchpad) (dossier) (atlas) (biography)\n │ │ │ │\n │ confidence │ confidence │ confidence │\n │ ≥ 0.5 │ ≥ 0.7 │ ≥ 0.9 │\n ▼ ▼ ▼ ▼\n Raw notes Focused task Cross-project Durable truths\n & ephemera context awareness\n```\n\n### Visibility Boundaries\n\n```\n PRIVATE ──▶ INSPECTABLE ──▶ SHARED ──▶ CANONICAL\n (agent-only) (scan only) (project) (read-only, global)\n```\n\n- `private` — Agent inner monologue, never visible to others\n- `inspectable` — Visible in envelope scans, body requires permission\n- `shared` — Available to all agents in the same project scope\n- `canonical` — Global read-only, requires confidence ≥ 0.9\n\n### FPEF v2.0 — First Principles Execution\n\nA 4-phase enforcement framework that prevents agents from jumping to solutions:\n\n| Phase | Name | Rule |\n|-------|------|------|\n| 1 | **FIND** | *No solutions allowed. Map reality only.* |\n| 2 | **PROVE** | *Verify every finding with concrete evidence.* |\n| 3 | **EVIDENCE** | *Validate. Test before trust.* |\n| 4 | **FIX** | *Minimal change, maximum impact.* |\n\n```typescript\nimport { FPEF } from \"prologue/fpef\";\n\nconst fpef = new FPEF({ strict: true });\n\n// Wrap any task with phase enforcement\nconst prompt = fpef.wrapPrompt(\"implement auth system\");\n\n// Validate agent output for violations\nconst violations = fpef.validate(agentOutput);\n// → [{ phase: \"find\", violation: \"proposed solution before FIND\", confidence: 0.95 }]\n\n// Anti-dishonesty checks (6 deterministic rules, no LLM calls)\nconst checks = fpef.antiDishonesty(agentOutput);\n// → [{ check: \"no_hope_based\", passed: false, violation: \"hope-based language: 'should probably work'\" }]\n\n// Catastrophic failure recovery (always returns 5 steps)\nconst steps = fpef.catastrophicFailure({\n classification: \"build_failure\",\n description: \"tsc fails on memory.ts\",\n affectedScope: [\"src/types/memory.ts\"],\n});\n// → ACKNOWLEDGE → ASSESS → ISOLATE → RECOVER → PREVENT\n```\n\n### Orchestrator\n\nAutomates the agent lifecycle — run tasks, capture learnings, store memories:\n\n```typescript\nimport { Orchestrator } from \"prologue/orchestrator\";\nimport { MemoryMatrix } from \"prologue\";\n\nconst memory = await MemoryMatrix.create(\"./my-project\");\nconst orch = new Orchestrator({ projectDir: \"./my-project\", memory });\n\n// Run a task — orchestrator spawns Claude Code, then auto-processes the session\nawait orch.run(\"refactor auth module to use RS256\");\n// → After completion: git diff analysis → insight extraction → memory storage\n```\n\n### MCP Server\n\nUse prologue as a Claude Code tool server:\n\n```json\n// .claude/settings.json\n{\n \"mcpServers\": {\n \"prologue\": {\n \"command\": \"npx\",\n \"args\": [\"prologue-mcp\"]\n }\n }\n}\n```\n\nFive tools exposed: `memory_store`, `memory_query`, `memory_promote`, `memory_envelope_scan`, `memory_delete`.\n\n### Python Bridge (Graphiti Integration)\n\nOptional Python bridge provides knowledge graph storage and embedding services:\n\n```bash\ncd python && uv run python -m src.main\n```\n\n- **Embedding providers:** OpenAI (text-embedding-3-small), Ollama (nomic-embed-text), Voyage AI (voyage-3)\n- **Knowledge graph:** Graphiti for persistent episodic memory\n- **Graceful fallback:** File-only mode when Python is unavailable\n\n## File Storage\n\n```\n{project}/.prologue/\n├── config.json\n└── memories/\n ├── working/{uuid}.json\n ├── project/{uuid}.json\n ├── overview/{uuid}.json\n ├── core/{uuid}.json\n └── index.json # All envelopes, bodies stripped\n```\n\nEach memory file is a `MemoryCell` (envelope + body). Atomic writes via tmp+rename prevent corruption.\n\n## API Reference\n\n### MemoryMatrix\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `MemoryMatrix.create(projectDir)` | `Promise` | Static factory, initializes directory structure |\n| `store(content, options?)` | `Promise` | Store a new memory |\n| `query(queryText, options?)` | `Promise` | Search memories (exact match + tags) |\n| `promote(memoryId, targetLevel)` | `Promise` | Move memory up compression ladder |\n| `envelopeScan(readerVisibility?)` | `Promise` | List envelopes respecting visibility |\n| `delete(memoryId)` | `Promise` | Delete a memory |\n\n### FPEF\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `wrapPrompt(task, options?)` | `string` | Inject phase instructions around a task |\n| `validate(output)` | `Violation[]` | Post-hoc output validation (deterministic) |\n| `antiDishonesty(output)` | `DishonestyCheck[]` | 6-rule anti-dishonesty checks |\n| `catastrophicFailure(report)` | `RecoveryStep[]` | 5-step failure recovery protocol |\n\n### RecoveryManager\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `classifyFailure(error)` | `FailureClassification` | Classify into 5 failure types |\n| `isCircularFix(edit, previous)` | `boolean` | Jaccard similarity > 0.3 detection |\n| `getRecoveryAction(class, attempt, circular)` | `RecoveryAction` | Graduated: retry → analyze → escalate |\n| `isStuck(failureId, attempts)` | `boolean` | True after 3 attempts on same failure |\n\n## Development\n\n```bash\nbun install # Install dependencies\nbun test # Run all 148 tests\nnpx tsc --noEmit # Type check\nbunx biome check . # Lint\nbunx biome format . --write # Format\n```\n\n## Testing\n\n148 tests across 12 files covering:\n\n- **MemoryMatrix** — store, query, promote, file persistence, atomic writes, envelope scan isolation\n- **Orchestrator** — task execution, post-session pipeline, git analysis, insight extraction, recovery manager\n- **FPEF** — phase gates, output validation, anti-dishonesty (6 rules), catastrophic failure protocol\n- **Integration** — 7 end-to-end scenarios from the spec\n\n```bash\nbun test # All tests\nbun test test/matrix/ # Memory matrix only\nbun test test/orchestrator/ # Orchestrator only\nbun test test/fpef/ # FPEF only\nbun test test/integration/ # E2E only\n```\n\n## Dependencies\n\n**Zero runtime dependencies** beyond Zod:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `zod` | ^4.3.6 | Runtime type validation |\n\n**Dev dependencies:**\n\n| Package | Purpose |\n|---------|---------|\n| `@types/bun` | Bun runtime types |\n| `typescript` | ^5.9.0 |\n\n## Tech Stack\n\n- **Runtime:** Bun (TypeScript strict mode)\n- **Validation:** Zod v4 (schemas + types, single source of truth)\n- **Testing:** bun:test\n- **Linting:** Biome\n- **Python Bridge:** uv + Pydantic + optional Graphiti/OpenAI\n- **MCP:** stdio transport (Claude Code compatible)\n\n## Project Structure\n\n```\nprologue/\n├── src/\n│ ├── index.ts # Barrel exports (public API)\n│ ├── types/ # Zod schemas + TypeScript types\n│ ├── matrix/ # MemoryMatrix, file store, search, promotion\n│ ├── orchestrator/ # Task orchestration, recovery, git analysis\n│ ├── fpef/ # FPEF v2.0, phase gates, validation, anti-dishonesty\n│ ├── bridge/ # Python bridge (TS side)\n│ └── mcp/ # MCP server (Claude Code integration)\n├── python/ # Python bridge (Graphiti + embeddings)\n├── test/ # 148 tests across 12 files\n├── CLAUDE.md # Claude Code agent instructions\n├── PROJECT-SPEC.md # Single source of truth specification\n└── PHASE-TASKS.yaml # Swarm execution task decomposition\n```\n\n---\n\n
\n\n**Built with precision by [aegntic.ai](https://aegntic.ai)**\n\n*a division of [ae.ltd](https://ae.ltd)*\n\n*Autonomous systems. First principles. No compromise.*\n\n
\n","readmeFilename":"README.md"}