DEV Community

Teycir Ben Soltane
Teycir Ben Soltane

Posted on

Giving Your AI Coding Agents a Shared Memory (So They Stop Forgetting Everything) published

#ai #productivity #mcp #opensource

The problem in one line

Butler's core value isn't just that an agent remembers — it's that the memory is portable across completely different AI tools, because it lives in a shared local SQLite file rather than inside any one vendor's session. That's what makes cross-tool continuity possible in the first place.

If you bounce between Claude Desktop, Cursor, and VS Code while coding, you've probably hit this wall: every time a session restarts, your agent forgets everything. TODOs, architectural decisions, why you rejected an approach an hour ago — gone. And if you run two agents on the same repo at once, they don't even know the other exists.

I built Butler to fix that: a local-first MCP server that gives coding agents a persistent, shared memory layer, without a cloud account, an API key, or a database server to babysit.

What Butler actually does

Butler runs as an MCP server backed by a single SQLite file (WAL mode) sitting in your project. It's event-sourced: every action — a TODO created, a rule added, a decision recorded — is appended to an immutable log. Current state is just a materialized view built by replaying that log.

🤖 Agent A (Claude)        🤖 Agent B (Cursor)
        \                      /
         [ MCP stdio transport ]
                   ↓
         ===================
         │      BUTLER      │
         │  Shared Memory   │
         ===================
         /      │      │      \
        ▼       ▼      ▼       ▼
    TODOs    Rules  Decisions  Wiki
Enter fullscreen mode Exit fullscreen mode

The killer scenario: you plan a migration in Cursor, it registers a session and creates a few TODOs. The window crashes. You open Claude Desktop instead — it registers its own session, pulls the shared context resource, and picks up exactly where Cursor left off: pending tasks, architectural decisions, everything. Zero re-explaining.

Core pieces

  • Sessions — ephemeral, heartbeat every 15s so Butler knows who's alive
  • Events — the ground truth, append-only
  • State — the cache, rebuilt from events
  • Handoffs — structured summaries generated automatically when a session disconnects, complete with a quality score and coaching feedback
  • Memory — semantic search over stored decisions/notes using pure-JS TF-IDF, no vector DB, no embeddings API

It also ships native LangGraph.js integration — a SQLite-backed checkpointer so multi-agent orchestration graphs (plan → implement → verify → commit) can persist their state in the same database as everything else.

Multi-agent coordination, not just memory

This is the part that matters once you have more than one agent touching a repo:

  • todoclaim / todounclaim — lock a task so two agents don't grab the same thing
  • Conflict detection — if two sessions mutate the same TODO within a 10-second window, Butler logs a TODO_CONFLICT event that shows up for everyone
  • broadcast / messagesend — agents can talk to each other, not just to you
  • Self-healing — a session that misses heartbeats for 60s goes stale; after 5 minutes it's dead, its claims are released, and Butler synthesizes a handoff automatically

There's also a live TUI (butler tui) if you want to watch this happen in real time:

┌─────────────────────────────────────────────────────────────┐
│ 🤵 BUTLER │ Project: api-hunter          ● 20:13:57          │
├───────────────────────────────┬───────────────────────────────┤
│ 👤 Sessions (2)                │ 🎯 Shared Tasks (3 open)       │
│  ● cursor-main-1   12s ago     │  🔒 JWT signature fix (cursor) │
│  ○ claude-desk-2   45s ago     │  ⬜ Add OAuth tests            │
├───────────────────────────────┴───────────────────────────────┤
│ ⚡ Conflicts: 1  │  Events: 142  │  Auto-refresh: 2s            │
└─────────────────────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

Getting started 

npx butler-mcp install   # auto-detects and configures Claude, Cursor, VS Code, Zed, Windsurf...
npx butler-mcp status
npx butler-mcp dashboard
Enter fullscreen mode Exit fullscreen mode

Drop a .butler/project.json in your repo (or let Butler auto-create one), and every tool call scopes itself to that project automatically. No project IDs to pass around by hand.

There's also a portable agent skill (skills/butler-workflow) that teaches any MCP-compatible agent the full lifecycle — register, heartbeat, claim, handoff, disconnect — so you don't have to hand-write those instructions into every client's system prompt.

Why SQLite + TF-IDF instead of the "proper" stack

Because the proper stack is the point of friction. A Postgres container or a hosted vector DB is one more thing to install, one more thing to leak data to, one more thing to break on a laptop with no internet. Butler's whole design bet is: local file, zero network calls, zero paid dependencies. If that means the search relevance is TF-IDF instead of embeddings, that's a trade I'll take for something that works offline and never phones home.

Try it

Repo's here: github.com/Teycir/Butler — MIT licensed. It supports Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Gemini CLI, Kiro CLI, and Kilo Code out of the box.

If you're juggling multiple AI coding tools and tired of re-explaining your project every time one of them restarts, I'd genuinely like to hear if this solves it for you — issues and PRs welcome.

Top comments (0)