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

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