🪨 Accrete

Compound knowledge for AI-native development

Each decision makes the next decision easier.

Quick Start • CLI Commands • How It Works • MCP Setup • Features • Roadmap

The Problem

The bottleneck in software delivery has shifted. Code production is no longer the constraint — specification, architectural coherence, and domain knowledge are.

OpenAI's Codex team shipped a million-line product with zero manually-written code. Three engineers drove 1,500 PRs in five months. Their most important finding:

"From the agent's point of view, anything it can't access in-context while running effectively doesn't exist."

Every architectural decision, trade-off, and rationale needs to live in the repository — structured, searchable, and legible to agents. But in most teams, this knowledge is scattered across:

💬 Slack threads no one can find
📝 Meeting notes no one reads
🧠 The head of that engineer who left six months ago
📄 README files outdated the day they were written

The result? Agents replicate bad patterns because they can't see the decisions that shaped the codebase. Architectural choices get reversed because no one — human or AI — remembers why they were made. Human taste, captured nowhere, is lost on every PR.

The Solution

The repository becomes the system of record. Decisions become infrastructure.

Not a wiki. Not a Google Doc. Version-controlled decision records that live in the repository — portable, forkable, and permanent. An MCP server makes them semantically searchable by AI agents in real-time. A graph database tracks how decisions relate to each other.

Accrete implements the context engineering layer for decisions — the part of the development harness that ensures agents understand not just what the code does, but why it was built that way.

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│   📋 STRATEGY      →    📦 PRODUCT      →    🏗️ ARCHITECTURE │
│   Why we exist          What we build        How we build   │
│                                                             │
│   SDRs                  PDRs                 ADRs           │
│   Vision & Model        Feature Specs        Tech Decisions │
│   Market Context        User Stories         Patterns       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                              ↓
              🤖 MCP Server + Kuzu Graph Database
                              ↓
         Agents query decisions semantically, in real-time

Human taste is captured once and enforced continuously. Every session starts informed. Every decision compounds.

Quick Start

🚀 Try It Out

Run instantly without installing:

npx accrete init        # Initialize in current directory
npx accrete status      # Check decision counts

⚡ Regular Use

Install globally for permanent access:

npm install -g accrete
accrete init
accrete status

Then in Claude Code, create decision records and inject context:

# Create decision records with LLM assistance
/accrete:decide --type adr "Use PostgreSQL for primary database"
/accrete:decide --type pdr "Mobile-first approach"
/accrete:decide --type sdr "Open source strategy"

# Or let the LLM guide you to the right type
/accrete:decide

# Inject decisions into CLAUDE.md for AI context
/accrete:inject

CLI Commands

`accrete init`

Initialize Accrete in your repository:

accrete init                    # Initialize with default settings
accrete init --force            # Reinstall templates (preserves decisions)
accrete init --project-name foo # Set custom project name

Creates:

.decisions/adr/, .decisions/pdr/, .decisions/sdr/ directories
.accrete/config.yml with project metadata
.accrete/templates/ with customizable decision templates

`accrete status`

View repository status and decision counts:

accrete status

Output:

Accrete Status

Project: my-project
Initialized: 2025-01-15
Version: 1.0.0

Decision Records

  ADR:   3  Architecture Decision Record
  PDR:   2  Product Decision Record
  SDR:   1  Strategy Decision Record

Total: 6 decisions

`/accrete:decide` (Claude Code Skill)

Create decision records with LLM assistance:

/accrete:decide --type adr "Use PostgreSQL"   # Specify type
/accrete:decide                                # Guided discovery

The skill:

Checks repository initialization
Guides you through gathering decision context
Asks clarifying questions about alternatives and consequences
Generates complete decision records with proper numbering

`/accrete:inject` (Claude Code Skill)

Inject decision summaries into CLAUDE.md for AI context:

/accrete:inject                    # Inject all accepted decisions
/accrete:inject --status           # Check if context is current
/accrete:inject --type adr         # Inject only ADRs
/accrete:inject --include-proposed # Include proposed decisions
/accrete:inject --all              # Include all statuses

The skill:

Reads decisions from .decisions/ and extracts summaries
Updates CLAUDE.md with a managed context section
Tracks injection state for change detection
Preserves existing CLAUDE.md content outside markers

`accrete conflict`

Detect and manage conflicts between decision records:

# Scan all decisions for conflicts
accrete conflict scan                    # Find all conflicts
accrete conflict scan --type semantic    # Filter by conflict type
accrete conflict scan --severity critical # Filter by severity
accrete conflict scan --include-dismissed # Include dismissed conflicts

# Check a specific decision
accrete conflict check ADR-001           # Check for conflicts involving ADR-001
accrete conflict check ADR-001 --strict  # Fail on any conflict (not just critical)

# Manage dismissed conflicts
accrete conflict dismiss <conflict-id> --reason "Justification here"
accrete conflict list                    # List all dismissed conflicts
accrete conflict restore <conflict-id>   # Restore a dismissed conflict

Conflict Types:

Type	Description
`semantic`	Contradictory technical positions (e.g., "use PostgreSQL" vs "avoid PostgreSQL")
`status`	Active decision references deprecated/superseded decision
`structural`	Circular supersession chains (A supersedes B supersedes A)
`scope`	Overlapping tags/areas without explicit relationship

Severity Levels:

Severity	Action Required
`critical`	Immediate attention - blocks deployment
`warning`	Should be addressed - may cause confusion
`info`	Awareness item - consider reviewing

`accrete benchmark`

Run SWE-bench-style benchmark comparisons with and without Accrete decision context:

# Run the default 20-task corpus
accrete benchmark run

# Filter to selected categories
accrete benchmark run --category bug-fix,feature

# Use CI-friendly JSON output with pass/fail thresholds
accrete benchmark run --output json --threshold-delta 15 --threshold-rate 50

# Generate ROI report (latest run)
accrete benchmark report

# Generate ROI report as JSON
accrete benchmark report --format json --team-size 8 --hourly-rate 90

# Analyze trend over recent runs
accrete benchmark trend --runs 10

# List tasks in a corpus
accrete benchmark list --corpus default

Set ANTHROPIC_API_KEY or OPENAI_API_KEY, then run accrete benchmark run for a real end-to-end benchmark run.

Benchmark command matrix:

Command	Purpose	Output
`accrete benchmark run`	Execute vanilla vs Accrete conditions for each task	Human summary or JSON
`accrete benchmark report`	Convert benchmark deltas to ROI and velocity metrics	Markdown or JSON
`accrete benchmark trend`	Analyze historical delta trajectory and anomalies	Human summary or JSON
`accrete benchmark list`	Inspect corpus tasks and category coverage	Human list

How It Works

📁 Structured Decision Records

Three layers of decisions, version-controlled alongside your code:

.decisions/
├── 📋 sdr/
│   ├── 001-vision-statement.md
│   ├── 002-competitive-positioning.md
│   └── 003-go-to-market-approach.md
├── 📦 pdr/
│   ├── 001-freemium-pricing-model.md
│   ├── 002-mobile-first-approach.md
│   └── 003-target-persona-definition.md
└── 🏗️ adr/
    ├── 001-use-postgresql-over-mongodb.md
    ├── 002-event-sourcing-for-audit-trail.md
    └── 003-monorepo-structure.md

🤖 AI Context Injection

Automatically load relevant decisions into every AI session:

# .accrete/config.yml
context_injection:
  session_start:
    - decisions/strategy/001-vision-statement.md
    - decisions/architecture/active/*.md
    - decisions/product/current-sprint/*.md

  on_file_change:
    pattern: "src/api/**"
    inject: "decisions/architecture/*api*.md"

🔌 Claude Code Integration

Available Now:

/accrete:decide     →  Create decision record with LLM assistance
                       Supports --type adr|pdr|sdr or guided discovery

/accrete:inject     →  Inject decision summaries into CLAUDE.md
                       Supports --status, --type, --include-proposed, --all

Available Now:

/accrete:search     →  Semantic search for decisions with natural language
                       Uses local embeddings (Xenova/all-MiniLM-L6-v2)

accrete conflict    →  Detect and resolve decision conflicts
                       scan, check, dismiss, list, restore

Coming Soon: (details)

/accrete:enrich     →  Fill missing sections in skeleton decisions
/accrete:review     →  Audit decision health and completeness

📝 Decision Templates

Decision records are created via the /accrete:decide Claude Code skill, which uses LLM assistance to help you document decisions comprehensively:

# In Claude Code
/accrete:decide --type adr "Use PostgreSQL for primary database"
/accrete:decide --type pdr "Mobile-first approach"
/accrete:decide --type sdr "Open source strategy"

Each template includes:

YAML frontmatter for AI parsing (type, status, date, authors, tags)
Guided sections with prompts for context, decision, consequences
Validation checklist to ensure completeness

Templates are bundled in templates/ and copied to .accrete/templates/ on init for customization.

Architecture

Accrete follows a local-first philosophy. No cloud dependencies, no subscriptions—everything runs on your machine.

┌──────────────────────────────┐     ┌──────────────────────────┐
│     AI Coding Assistants     │     │   accrete-web (React)    │
│ (Claude Code, Cursor, etc.)  │     │   Decision Dashboard     │
└──────────────┬───────────────┘     └────────────┬─────────────┘
               │ MCP Protocol                     │ HTTP/WS
               └──────────────┬───────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        accrete CLI                               │
│  ┌───────────┐ ┌───────────┐ ┌────────────┐ ┌────────────────┐ │
│  │ Context   │ │  Search   │ │ Conflict   │ │   Decision     │ │
│  │ Injection │ │ (Semantic)│ │ Detection  │ │   Lifecycle    │ │
│  └───────────┘ └───────────┘ └────────────┘ └────────────────┘ │
└───────────────────────────┬─────────────────────────────────────┘
                            │
        ┌───────────────────┴───────────────────┐
        ▼                                       ▼
┌───────────────────┐               ┌───────────────────────────┐
│  Kuzu (Local)     │     sync      │   .decisions/ (Git)       │
│  Graph + Vector   │ ◄───────────► │   Source of Truth         │
│  .kuzu/           │               │   sdr/ pdr/ adr/          │
└───────────────────┘               └───────────────────────────┘

Why Kuzu?

Accrete uses Kuzu, an embedded graph database with built-in vector search for unified decision storage, relationship tracking, and semantic search.

Requirement	Kuzu	Cloud Alternatives
🔒 Privacy	Data stored locally in `.kuzu/`	Requires data upload
💰 Cost	Free (Open Source)	Usage-based pricing
📡 Offline	Full functionality	Requires internet
🚀 Setup	`npm install` (No Python/Docker)	API keys, accounts, config
🔄 Portability	Commit index to git (optional)	Separate sync/migration
🔗 Relationships	Native graph traversal	Requires additional services
🔍 Search	Vector + graph in one database	Multiple services needed

Features

Feature	Description
📝 Decision Templates	ADRs, PDRs, SDRs with consistent structure
🧠 Context Injection	Inject decision summaries into CLAUDE.md
🔍 Hybrid Search	Semantic + keyword search with reranking
🔄 Decision Lifecycle	Proposed → Accepted → Deprecated → Superseded
🌳 Repository-Native	No external services, everything in git
🤖 AI-First	Structured for machines, readable for humans
🔌 MCP Integration	Native Claude Code support via MCP protocol
🔍 Conflict Detection	Detect semantic, status, structural, scope conflicts

Design Philosophy

Built for agent-first development, informed by production harness engineering:

Principle	Implementation
Agent Legibility	Decisions structured for machine consumption. MCP server enables real-time semantic queries. Agents reason about architectural context without human mediation.
Git = Source of Truth	Kuzu graph database is a cache that rebuilds from `.decisions/`. No sync issues, no migrations.
Graph + Vector Search	Combine semantic similarity with relationship traversal for intelligent results
Layered Context	Strategy → Product → Architecture hierarchy enables smart relevance
Lazy Initialization	Index builds on-demand, not at startup. Fast `git clone`, fast first run.
Graceful Degradation	Works without index (pattern matching), better with it (semantic + graph search)
Native Node.js	No Python dependencies, pure JS/TS stack for easier installation.

The Compound Effect

OpenAI's key insight about agent failures: "The fix was almost never 'try harder.' Human engineers always asked: 'what capability is missing, and how do we make it both legible and enforceable for the agent?'"

Accrete turns that fix-the-environment loop into a permanent record:

Session	Without Accrete	With Accrete
1	Explain architecture from scratch	Agent queries ADRs, understands patterns
10	Still explaining basics	Agent operates as informed team member
50	Knowledge scattered, inconsistent decisions	Compound knowledge, consistent evolution
100	New hire takes months to onboard	Full context in first `git clone`

Every decision documented makes the next decision easier. Every agent failure fixed at the decision level prevents the same failure across every future task.

Requirements

Requirement	Version	Purpose
Node.js	≥18.0.0	CLI, embeddings, and database
Git	Any recent version	Version control
AI Assistant	Claude, GPT, Gemini, or any LLM	Context consumption

Note: Accrete uses Kuzu (embedded graph database with native Node.js bindings) - no Python or Docker required.

Roadmap

Phase 1: Foundation ✓

Decision record templates (ADR, PDR, SDR)
CLI for decision management (accrete init, accrete status)
Claude Code skill (/accrete:decide) with LLM-assisted decision creation
Basic context injection (/accrete:inject) into CLAUDE.md

Phase 2: Intelligence (Kuzu) ✓

Local Kuzu graph database (Node.js) for unified storage and search
Claude Code skill (/accrete:search) for semantic search with natural language
Local embeddings with Transformers.js (Xenova/all-MiniLM-L6-v2)
Graph-based relationship tracking (supersedes, references, enables)
Impact analysis (accrete impact) - what decisions depend on this?
Decision chain traversal (accrete chain) - trace decision lineage
Path finding between decisions (accrete path)
Search with relationships (accrete search --with-references)
Decision conflict detection (scan, check, dismiss, restore)

Phase 3: MCP Integration ✓

MCP server for Claude Code (accrete mcp start)
MCP tools (accrete_query, accrete_context, accrete_create_decision)
Real-time context injection via MCP resources
Decision creation from conversation context
File watching for live updates
See MCP Setup Guide for configuration instructions

Phase 3.5: Decision Pipeline (details)

Rich decision creation - structured fields in accrete_create_decision (alternatives, consequences, tags)
Pre-creation duplicate check - accrete_check_decision MCP tool
Decision update capability - accrete_update_decision MCP tool (status, tags, relationships)
/accrete:enrich skill - fill missing sections in skeleton decisions
/accrete:review skill - audit decision health (skeletons, stale, orphans)
Improved detection confidence - reduce false positive interruptions
Fix /accrete:search to use MCP tool instead of CLI
Deprecation suggestions based on age and references

Phase 4: Web Interface

React-based dashboard for decision browsing
Decision timeline and relationship visualization
Search interface with semantic and graph search results
Decision lifecycle management (create, supersede, deprecate)
Real-time sync with .decisions/ directory and Kuzu graph database

Phase 5: Ecosystem & Integrations

Spec-Kit Integration: Seamless workflow with /speckit.specify, /speckit.plan, /speckit.implement
BMAD-Inspired Agents: Standalone personas (/accrete.architect, /accrete.pm, /accrete.dev)
GitHub Actions for decision validation
IDE extensions (VS Code, JetBrains)
Multi-model AI support
Enterprise features (SSO, audit logs)
BMAD Bridge (optional): Agent customization files for full BMAD installations
Party Mode: Multi-agent collaboration for complex decisions

Phase 6: Automatic Code Benchmark (In Progress)

SWE-bench-style benchmark harness with self-contained task corpus
Comparative analysis of AI performance with/without Accrete context
Automated ROI and velocity reporting (latest report)
Expand corpus beyond default 20 tasks
Multi-model comparison support

The Name

Accrete /əˈkriːt/ — to grow or accumulate gradually

In astronomy, accretion is how planets form: particles collect, gravity increases, more particles collect. Each addition makes the next more likely.

That's compound knowledge. Each decision documented makes the next decision easier. The knowledge doesn't just persist—it accretes.

Contributing

We welcome contributions of all kinds:

🍴 Fork the repository
🌿 Create a feature branch (git checkout -b feature/amazing)
💾 Commit your changes (git commit -m 'Add amazing feature')
📤 Push to the branch (git push origin feature/amazing)
🔃 Open a Pull Request

Areas We Need Help

📝 Decision templates for specific domains
📚 Documentation and examples
🐛 Bug reports and feature requests

License

"The best time to document a decision was when you made it.
The second best time is now."

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.accrete		.accrete
.benchmarks		.benchmarks
.claude/commands		.claude/commands
.codex		.codex
.decisions		.decisions
.github/workflows		.github/workflows
.specify		.specify
docs		docs
skills		skills
src		src
templates		templates
tests		tests
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

🪨 Accrete

The Problem

The Solution

Quick Start

🚀 Try It Out

⚡ Regular Use

CLI Commands

accrete init

accrete status

/accrete:decide (Claude Code Skill)

/accrete:inject (Claude Code Skill)

accrete conflict

accrete benchmark

How It Works

📁 Structured Decision Records

🤖 AI Context Injection

🔌 Claude Code Integration

📝 Decision Templates

Architecture

Why Kuzu?

Features

Design Philosophy

The Compound Effect

Requirements

Roadmap

Phase 1: Foundation ✓

Phase 2: Intelligence (Kuzu) ✓

Phase 3: MCP Integration ✓

Phase 3.5: Decision Pipeline (details)

Phase 4: Web Interface

Phase 5: Ecosystem & Integrations

Phase 6: Automatic Code Benchmark (In Progress)

The Name

Contributing

Areas We Need Help

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`accrete init`

`accrete status`

`/accrete:decide` (Claude Code Skill)

`/accrete:inject` (Claude Code Skill)

`accrete conflict`

`accrete benchmark`

Packages