backlog-mcp
A local-first, Markdown-backed engine for agent context and memory.
Tasks, decisions and memories share one store across MCP clients, the CLI
and a live read-only viewer. Humans can read, edit and diff the files directly.
Entities are Markdown with YAML frontmatter. A project’s substrate declarations
own its types, fields and workflows. Local hybrid search combines text and
embeddings; progressive disclosure keeps orientation small and expands content
when the agent needs it.
Install
Requires Bun 1.4.2 or newer.
Add this to .mcp.json or your MCP client configuration:```json
{
"mcpServers": {
"backlog": {
"command": "bunx",
"args": ["--bun", "backlog-mcp"]
}
}
}
For agent-assisted setup, ask your agent to read and follow the
installation skill.
The default command starts a persistent local HTTP server and bridges MCP stdio
requests to it. See installation and server lifecycle.
## Quick start
From your project directory, explicitly select its home (even without `docs/` yet):```bash
bunx --bun backlog-mcp --home project --project-root . wakeup
bunx --bun backlog-mcp --home project --project-root . create "Fix authentication flow" --content "Investigate the failing login."
bunx --bun backlog-mcp --home project --project-root . list --type task
bunx --bun backlog-mcp --home project --project-root . recall "authentication decisions"
bunx --bun backlog-mcp --home project --project-root . remember "Describe one verified durable login convention." --title "Login convention" --layer semantic
For MCP task work, discover and inspect the full schemas of
backlog_create_work, backlog_start_task and backlog_complete_task.
The Markdown body field is content; declarations may add required fields.
Wake up once at session start. Recall when prior knowledge matters, inspect its
age and correction lineage, then expand selected entities with backlog_get
(context: true includes relation stubs). Remember one durable fact per memory;
correct an old fact with supersedes or state_key.
See the memory protocol.
Viewer
Open localhost:3030 while the server is running.
The Desk surfaces at most seven attention items
with provenance and copy-ready instructions for your agent. The viewer provides
search, entity detail, activity and live updates; edits flow through your agent
or native Markdown files. See viewer usage.
Documentation
- Documentation map: users, contributors and historical decisions.
- Commands and entities.
- Homes, configuration and migration.
- Claude Code session hooks.
- Development, testing and releases.
- ADR index and product direction.
Local Markdown remains the source of truth. Legacy Workers/D1 hosting is retained
and descoped; see the installation guide.
MIT licensed. npm package ·
Maintainer’s engineering story.
