Welcome.
This is a framework for local-running personal and public agents.
Although it doesn't try to take itself too seriously.
Some contents of this site may be adult-themed (for no specific reason).
____ __ __ ______ / __ )__ __/ /_/ /_/ ____/___ ________ / __ / / / / __/ __/ / / __ \/ ___/ _ \ / /_/ / /_/ / /_/ /_/ /___/ /_/ / / / __/ /_____/\__,_/\__/\__/\____/\____/_/ \___/
File-native agent memory. Human-readable. Git-diffable. Tool-agnostic.
Seven markdown files plus AGENTS.md. Global identity lives in ~/.buttcore/. Project context stays in .buttcore/ inside each project directory. A scope boundary enforces separation. Corrections, mistakes, and vocabulary accumulate in raw form until the distillation process compresses them into durable, confidence-scored principles. No database. No API keys for behavioral configuration. Just files and the intelligence to maintain them.
# ButtCore
Drop-in markdown files that teach AI agents to learn and evolve from your habits.
## What This Is
ButtCore is a set of markdown files you drop into any project directory. As you work with any AI agent — Claude, GPT, Cursor, Copilot, Codex, Gemini — the system observes, learns, distills, and updates itself.
It maintains a living `SOUL.md` file: a continuously evolving instruction set that reflects your preferences, communication style, technical decisions, corrections, and patterns.
**No database. No API keys. No configuration. Just markdown and intelligence.**
## Install
```bash
npx buttcore init
```
This creates:
- `~/.buttcore/` (global, shared across all projects)
- `SOUL.md` — Living identity and preferences
- `PATTERNS.md` — Cross-project patterns
- `MISTAKES.md` — Process failure lessons
- `LEXICON.md` — Your personal vocabulary
- `.buttcore/` (local to this project)
- `PROJECT.md` — Project-specific context
- `SESSION_LOG.md` — Rolling session history
- `CORRECTIONS.md` — Correction tracking
- `AGENTS.md` — Cross-tool bridge file
## How It Works
1. **Agent reads** ButtCore files at session start
2. **You work** with the agent normally
3. **When corrected**, the agent logs to CORRECTIONS.md
4. **When patterns emerge** (3+ similar corrections), the Distillation Process triggers
5. **Distilled knowledge** flows to the appropriate file (SOUL.md, MISTAKES.md, LEXICON.md, PATTERNS.md)
6. **Next session**, the agent is better
The learning is real. Not "I'll try harder" — structural, persistent, versioned knowledge that survives across sessions, projects, and even different AI tools.
## Commands
| Command | What it does |
|---------|-------------|
| `buttcore init` | Initialize ButtCore in current project |
| `buttcore onboard` | Interactive questionnaire to pre-populate SOUL.md |
| `buttcore status` | Show current learning state |
| `buttcore compact` | Compress old session logs |
| `buttcore export` | Export all knowledge to a single file |
| `buttcore doctor` | Validate file integrity |
## Philosophy
### Global vs Local
ButtCore enforces a strict scope boundary:
- **Global** (`~/.buttcore/`): Who you are. Applies everywhere.
- **Local** (`.buttcore/`): What this project is. Stays here.
Project-specific data never leaks into global files. Global knowledge is abstract and generalizable.
### Confidence Escalation
Not every observation becomes a rule:
| Signal | Where it goes | Confidence |
|--------|--------------|------------|
| 1 occurrence | SESSION_LOG.md | — |
| 2 occurrences | SOUL.md | low |
| 5 occurrences | SOUL.md | medium |
| 10+ occurrences | SOUL.md | high |
### The Agent Learns From Its Mistakes
MISTAKES.md doesn't just record what the user wants — it records what the agent got wrong and why. "I defaulted to complex when the user meant simple" is more valuable than "user prefers simple."
## Works With
Any AI agent that can read files in your project:
- Claude Code / Claude Desktop
- Cursor (reads AGENTS.md + .cursor/rules/)
- GitHub Copilot (reads AGENTS.md)
- OpenAI Codex
- Windsurf
- Aider / OpenCode / Goose
- Any custom agent with filesystem access
## License
MIT
The living identity file. Communication style, technical defaults, decision-making patterns, and distilled lessons from past corrections. Updated through the confidence escalation protocol - single observations log to SESSION_LOG, repeated patterns earn promotion. Confidence levels gate every entry.
Raw correction data with full incident context. When a user pushes back, the event is logged before any abstraction occurs. Three related corrections trigger distillation - the system compresses specifics into principles and determines the correct destination file.
Process failures, not preference mismatches. Why the agent failed, not just what the user wanted differently. An agent that remembers "the user likes minimal styling" but forgets "I generated Material UI three times before understanding what minimal meant" has learned the fact but not the lesson.
Vocabulary mapping. When a user says "simple," what do they mean? When they say "clean it up," what changes? Personal shorthand decoded into concrete behavioral instructions the agent can follow without asking.
Project-specific architecture, technology choices, constraints, and open questions. Everything in this file is local. Nothing here leaks upward unless the distillation process confirms it as a cross-project pattern and abstracts it accordingly.
Rolling record of recent sessions, signals, and distillation candidates. Auto-compacted over time. The staging area for observations that have not yet earned promotion to global knowledge.
The cross-tool entry point. Tells Cursor, Copilot, Claude Code, Codex, and any file-reading agent where to find ButtCore and how to participate in the learning loop. The bridge between the protocol and whatever tool the developer is using today.
A .scope_boundary marker file enforces directional data flow. Local observations promote upward only through distillation, which requires abstraction. "User chose PostgreSQL for this project" becomes "user defaults to established relational databases." Global files never reference specific projects. Data never flows down.
No database means no infrastructure dependency. No API keys means no configuration ceremony. Files are portable - copy them to a new machine, check them into version control, read them yourself. Any sufficiently capable agent can maintain them. The format is the distribution mechanism.