Twining MCP server
Commit Oct 7, 2026Provides AI agents with persistent project memory to record decisions, track rationale, and coordinate context across multiple sessions.
Also known as daveangulo/twining-mcp
- Stars
- 7
- Tools
- 15
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 7, 2026
- License
- MIT
What is Twining MCP?
Twining provides AI agents with persistent project memory to record decisions, track rationale, and coordinate context across multiple sessions. It exposes 15 tools, such as twining_assemble, twining_record, twining_post.
Summary generated from the project's README
About Twining MCP server
Giving AI agents a way to remember architectural decisions and project rationale across different sessions is what twining-mcp enables. It provides a persistent memory layer for Claude Code and other MCP clients, ensuring that when a session ends, the reasoning behind choosing specific technologies or identifying bugs is not lost. This prevents agents from contradicting previous choices or repeating explanations in new sessions.
Developers use the twining_record tool to save summaries, decisions, and assumptions in natural language, while twining_assemble allows an agent to pull relevant context into a new task based on a specific scope and token budget. The server also includes twining_why to trace the decision chain for specific files. It functions as a dynamic blackboard that coordinates multiple agents by sharing state outside of their individual context windows.
Setup is handled via a plugin marketplace for Claude Code or through standard MCP configuration for clients like Cursor or Windsurf. It uses a local .twining directory to store the project's institutional memory and can be configured to enforce recording decisions through pre-commit hooks.
What you can do with it
- 1Preserving architectural decisionsAn agent can record why a specific database or authentication method was chosen to prevent future sessions from suggesting alternatives.
- 2Coordinating multi-agent workflowsDifferent AI agents can stay aligned on project standards by reading a shared state that exists outside their individual context windows.
- 3Context-aware task initializationWhen starting a new task, an agent can selectively retrieve only the most relevant past decisions to fit within its token limits.
- 4Tracing technical rationaleA developer can ask an agent to explain the history and reasoning behind the implementation of a specific file.
Written from the project's README. Every use case is checked against a quote from it.
Twining MCP tools 15
Detected from the READMEtwining_assembletwining_recordtwining_posttwining_resolvetwining_whytwining_statustwining_housekeepingtwining_archivetwining_archive_staletwining_unarchivetwining_add_entitytwining_add_relation
Show all 15 toolsShow fewer tools
twining_neighborstwining_graph_querytwining_prune_graph
Configuration
TWINING_DISABLEDTWINING_PROJECT
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabledaveangulo/twining-mcp is public and reachablegithub.com/daveangulo/twining-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-07github.com/daveangulo/twining-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model15 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubThe Problem
You spend two hours with Claude Code making architectural decisions. You choose PostgreSQL over MongoDB. You settle on JWT for auth. You flag a race condition in the payment module. Then the session ends.
Tomorrow you start a new session. Claude has no idea what happened. The decisions are gone. The warnings are gone. The rationale is gone. You re-explain everything — or worse, Claude silently contradicts yesterday's choices.
This gets worse with multiple agents. Agent A decides on REST. Agent B picks gRPC for the same service. Neither knows the other exists. You find out when the code doesn't compile.
Context windows are ephemeral. Your project's decisions shouldn't be.
How Twining Fixes It
Twining is an MCP server that gives your AI agents persistent project memory. Decisions survive context resets. New sessions start informed. Multi-agent work stays coordinated.
# Install in 10 seconds
/plugin marketplace add daveangulo/twining-mcp
/plugin install twining@twining-marketplace
Record what you did — in natural language:
twining_record({
summary: "Added Redis caching to UserService",
decisions: ["Chose Redis over Memcached — need persistence across restarts"],
assumptions: ["Read-heavy workload (10:1 ratio)"],
scope: "src/services/"
})
Twining parses your decisions into structured records — extracting rationale, rejected alternatives, and domain automatically. One tool call, no forms.
Start a new session. Get caught up instantly:
twining_assemble({ task: "optimize the caching layer", scope: "src/services/" })
Twining scores every decision, warning, and finding by relevance to your task, then fills a token budget in priority order. You get exactly the context you need — no firehose, no re-explaining.
Ask why things are the way they are:
twining_why({ scope: "src/auth/middleware.ts" })
Returns the full decision chain for any file: what was decided, when, why, what alternatives were rejected, and which commit implemented it.
Why Not Just Use CLAUDE.md?
CLAUDE.md is static. You write it once and update it manually. It doesn't capture decisions as they happen, doesn't track rationale or alternatives, doesn't detect conflicts between agents, and can't selectively assemble context within a token budget.
Twining is dynamic. Every twining_record call captures decisions with their rationale and rejected alternatives. Every twining_post shares a finding or warning. Every twining_assemble scores relevance and delivers precisely what the current task needs. The .twining/ directory is your project's living institutional memory.
The two are complementary, not rivals: CLAUDE.md is the right home for standing instructions ("always run the linter"), Twining for the accumulating record of what was decided and why.
Why Not an Orchestrator?
Orchestrators (like agent swarms and hierarchical coordinators) route work by assigning tasks. Twining coordinates by sharing state. The difference matters:
- Orchestrators hold coordination context in their own context window — a single point of failure that degrades as the window fills
- Twining's blackboard persists coordination state outside any agent's window, surviving context resets without information loss
Agents self-select into work by reading the blackboard. No central bottleneck. No relay that drops context. Every agent sees every other agent's decisions and warnings, directly.
Install
Plugin Install (Recommended)
# Add the marketplace (one-time)
/plugin marketplace add daveangulo/twining-mcp
# Install the plugin
/plugin install twining@twining-marketplace
Includes the MCP server, skills, lifecycle hooks, and pre-commit enforcement. Two gates: twining_assemble before working, twining_record before committing.
To be precise about what "enforced" means, since it differs per gate: Gate 2 is hook-enforced — a pre-commit hook blocks git commit until this session has recorded, and a Stop hook asks for a record before the session ends. Gate 1 is instruction-only — it is injected into the session by the SessionStart hook and the MCP server's instructions, and nothing blocks an agent that skips it. In practice compliance is high (a field project measured 90.7% of decisions recorded after an assemble), but it is a convention the agent follows, not a wall.
Team Auto-Install
Commit this to your repo's .claude/settings.json so every team member gets Twining on clone:
{
"extraKnownMarketplaces": {
"twining-marketplace": {
"source": {
"source": "github",
"repo": "daveangulo/twining-mcp"
}
}
},
"enabledPlugins": {
"twining@twining-marketplace": true
}
}
When team members trust the repository folder, Claude Code automatically installs the marketplace and plugin.
v2 is stable: v2.0.0 (sqlite-by-default, Node >= 22.13) ships on the default npm channel — plain
npx -y twining-mcpgets it. Existing v1 projects keep working unchanged; the sqlite migration is opt-in vianpx twining-mcp migrate. See docs/UPGRADE-v2.md.
MCP-Only Install
For non-Claude-Code clients (Cursor, Windsurf, etc.):
claude mcp add twining -- npx -y twining-mcp --project .
Or add to .mcp.json:
{
"mcpServers": {
"twining": {
"command": "npx",
"args": ["-y", "twining-mcp", "--project", "."]
}
}
}
MCP server instructions are included automatically in the initialize response.
Troubleshooting: the twining tools aren't there
Twining fails quiet — when the server can't start, no error surfaces in the session and the tools simply never appear. Work through this in order:
-
Ask an agent what it can actually see. Have it run
ToolSearchfortwiningand report the raw result, or run/mcp. Do not infer from behavior; agents will substitute plausible-looking alternatives rather than report a missing tool. -
If
ToolSearchfinds nothing, the server isn't running. Probe the launcher directly:bash "$CLAUDE_PLUGIN_ROOT/scripts/launch-server.sh" --probe # → runner=<rung> node=<version>runner=nonemeans every resolution rung failed — see the next section.A healthy
runner=does not mean the server can start. The probe checks thatnpxruns, not that it can fetch the package. A registry policy (npm'sminimumReleaseAge, common in corporate setups), an auth or proxy failure, or simply being offline all producerunner=npxand then a dead launch. Since plugin 1.24.0 the launcher detects that and falls back to the bundled server automatically; on older plugins it exits with npx's error, which appears in the MCP log below. -
Check the MCP log for the real error:
~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-twining/on macOS. -
Check that the plugin is enabled in this configuration.
/pluginshows what the current session loaded. A differentCLAUDE_CONFIG_DIR, or a worktree without the project-scope settings, can load no plugin at all — no MCP, no hooks, no skills. -
If tools exist in your main session but not in a spawned agent, see Agent teams and subagents below.
While the server is down, the commit gate still applies in an initialized checkout. Bypass with TWINING_DISABLED=true git commit ... and note key decisions in your summary so a connected session can record them.
PATH-restricted environments (agent teams, GUI launches)
When Claude Code is spawned with a minimal environment — agent-team teammates (e.g. cmux split panes), GUI-launched apps, some CI shells — the directory holding npx (Homebrew, nvm, etc.) may not be on PATH. The stdio server then fails to spawn and twining's tools are silently absent: no error surfaces in the session, the tools just never appear. Confirm by checking the MCP log (~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-twining/ on macOS) for:
Connection failed: Executable not found in $PATH: "npx"
Fix (macOS/Linux): wrap the server command in a login shell so PATH is rebuilt from the login profile (path_helper on macOS):
{
"mcpServers": {
"twining": {
"command": "sh",
"args": ["-lc", "exec npx -y twining-mcp --project ."]
}
}
}
The plugin's bundled server does this automatically since plugin 1.13.0 — it spawns through sh -c and recovers a usable PATH inside scripts/launch-server.sh, so plugin users need no per-project fix. The manual snippet above is only for standalone .mcp.json installs. If even a login shell can't find npx, the plugin's SessionStart hook detects it and injects a warning into the session instead of failing silently — and since plugin 1.18.0 the launch itself falls back through a ladder of alternatives first (next subsection).
Windows: the bundled server's sh launcher does not resolve there. Windows sessions inherit the registry PATH and never had the minimal-PATH problem, so the fallback is a one-line project .mcp.json with the bare command instead: "command": "npx", "args": ["-y", "twining-mcp@^2.0.0", "--project", "."] (the plugin's hooks, skills, and gates are unaffected).
Node installed but npm/npx missing
A login shell only fixes off-PATH npx — some environments have node with no npm/npx at all. Common cases: Debian/Ubuntu's nodejs apt package (npm is a separate package there), Alpine's nodejs apk (same), Amazon Linux 2023 when the nodejs-npm subpackage isn't installed, nix's nodejs-slim (deliberately npm-free), and version-manager shims (nvm/asdf/volta) left pointing at a removed install.
Since plugin 1.19.0, node-only environments work fully — offline included. The bundled server launches through plugin/scripts/launch-server.sh, which walks a resolution ladder and execs the first rung that works:
TWINING_SERVER_JSoverride — set it to any server entry point and the script runsnode "$TWINING_SERVER_JS"directly. Beats every other rung; intended for development builds and unusual layouts.- Project pin —
./node_modules/twining-mcp/dist/index.js(relative to the project root), if the project hastwining-mcpinstalled locally (npm i -D twining-mcp). A project pin outranks the npm rungs and the plugin's bundled copy, so a project can hold its server version independent of plugin updates. npxfrom the recoveredPATH— the normal case. Since 1.24.1 recovery merges the login-shellPATHahead of the inherited one (a~/.profilethat assignsPATHwithout a$PATHpassthrough can no longer clobber a workable inheritedPATH), and ifnodeis still unresolvable it appends well-known install dirs that exist (~/.local/bin,/opt/homebrew/bin,/usr/local/bin, volta/asdf/mise shims) — covering dirs that only interactive rc files add;- npm's
npx-cli.jsresolved relative to thenodebinary itself (<node bin>/../lib/node_modules/npm/bin/npx-cli.js) — this self-heals broken version-manager shims and installs where npm exists but isn't onPATH; - a globally installed
twining-mcp, if present; - the plugin-bundled server — a dependency-free single-file bundle shipped with the plugin, run directly with
node(requires Node >= 22). No npm, no npx, no network: a bare distro Node is enough for a fully working server, offline included. On this rung semantic search degrades to keyword mode, announced with a one-line stderr notice.
Only when every rung fails — no Node at all, or Node too old for the bundle — does the script exit 127 with guidance on stderr, and the plugin's SessionStart hook (which probes the same script via --probe) injects an explicit warning into the session. In that state the commit gate still applies in initialized checkouts (a .twining/ directory exists but no server is reachable); bypass a blocked commit in the interim with:
TWINING_DISABLED=true git commit ...
Full semantic search still needs the real npm package (the bundle ships without the embedding dependency). On a distro Node without npm, install npm alongside it:
- Debian/Ubuntu:
sudo apt install npm - Alpine:
apk add npm - Amazon Linux 2023:
sudo dnf install nodejs-npm(versioned streams use e.g.nodejs22-npm) - or reinstall Node from nodejs.org, which bundles npm
Once npm is present the ladder resolves the full package via npx automatically; running npm i -D twining-mcp in the project additionally pins it (rung 2) so the server version is under project control.
Manual MCP-only installs (the .mcp.json snippets above) are unaffected — they point at npx directly, as before.
Upgrading from Manual Install
If you previously configured Twining manually, switch to the plugin:
- Remove manual MCP server:
claude mcp remove twining - Install plugin:
/plugin marketplace add daveangulo/twining-mcpthen/plugin install twining@twining-marketplace - Clean up: remove Twining hooks from
.claude/settings.json, remove.claude/agents/twining-aware.mdif present, remove Twining sections fromCLAUDE.md(skills handle this now) - Keep:
.twining/directory (all state preserved) - Verify:
/twining:status
Get the Most Out of It
The plugin handles agent instructions automatically via skills. For the MCP-only install path, add Twining instructions to your project's CLAUDE.md so agents use it automatically — see docs/CLAUDE_TEMPLATE.md for a ready-to-copy template.
Shared Store Across Repos
By default the server uses the project it starts in. To point several sibling repos at one coordination store (so cross-repo agents see each other's decisions and blackboard), set TWINING_PROJECT in each repo's .claude/settings.json:
{ "env": { "TWINING_PROJECT": "/path/to/shared-chassis" } }
Resolution order: --project <arg> > $TWINING_PROJECT > cwd. Relative values resolve against the server's working directory (the repo root); absolute paths are recommended for multi-machine setups. This replaces the old pattern of a per-repo .mcp.json override plus an exact-command deniedMcpServers block, which silently broke on every plugin version bump.
Git Worktrees & Agent Teams
When the project root is a linked git worktree (its .git is a gitdir: file pointing into the main checkout's .git/worktrees/), Twining resolves to the main checkout's .twining by default. Agent teammates spawned into worktrees (e.g. claude-teams --worktree) previously forked the store — their decisions and records landed in a worktree-local .twining the main session never saw. Now all worktrees of a repo share one store, with the same gate semantics as multiple sessions working in one directory.
Two overrides:
--project/TWINING_PROJECTalways win — an explicit project is never redirected.TWINING_WORKTREE_LOCAL=trueopts out, keeping a worktree-local store.
The plugin's hooks apply the same resolution (and honor TWINING_PROJECT). Submodules are not affected — their gitdir: files point at .git/modules/, not .git/worktrees/.
Agent teams and subagents
Spawned agents do not automatically inherit Twining's tools, and when they don't, they fail quietly — an agent with no twining_* tools will often improvise (reading .twining/ with sqlite3 or jq) rather than report the gap. Two independent things have to hold.
1. The server has to be running for that session. Teammates launched in separate panes or processes get their own MCP connection. If the launcher can't resolve a runtime there, no agent in that session gets Twining tools, generic or otherwise. Diagnose with the troubleshooting steps above — this is the more common cause by far.
2. The agent definition must not restrict its tools. MCP tool names are namespaced at runtime by the server they came from: mcp__plugin_twining_twining__twining_assemble under a plugin install, mcp__twining__twining_assemble under a standalone .mcp.json. A custom agent whose frontmatter declares a tools: allowlist gets only what it lists, and entries that match nothing are dropped silently — so a bare twining_assemble in an allowlist yields no tool and no warning. Because the correct prefix depends on how Twining was installed, hardcoding one breaks the other install mode.
The reliable pattern is to omit tools: entirely so the agent inherits whatever the session exposes, and to have the agent locate the tools with ToolSearch rather than assuming a name. If you must restrict tools, include ToolSearch so the agent can still discover what it has.
When you dispatch agents, tell them explicitly: report it if the Twining tools are absent, rather than working around it. A silent substitution produces work that looks coordinated and isn't.
Where to set TWINING_PROJECT: in an environment both the hooks and the MCP server actually see — an exported terminal/session environment (a launcher wrapper, direnv, the shell you start Claude Code or cmux from). Avoid the two tempting-but-wrong places: .claude/settings.json env is currently not delivered to plugin-spawned MCP servers (hooks would redirect while the server doesn't — the gates then check a store the server never writes), and a machine-wide shell-profile export activates the commit/stop gates in every repo on the machine, including ones that never used Twining.
Dashboard
A web dashboard starts automatically at http://localhost:24282 — browse decisions, blackboard entries, knowledge graph, and agent state. Configurable via TWINING_DASHBOARD_PORT.
Built to stay usable at scale: lists are virtualized with live facet counts, the decisions timeline is a zoomable density histogram that switches to individual items as you zoom in, and the knowledge graph opens as a readable type-level overview you drill into (never a hairball). Every view respects the scope breadcrumb, and the URL captures tab/filters/selection for shareable deep links.
What's Inside
Core Tools (always available)
The full default surface is these 15 tools. Everything else needs full_surface: true — if a tool is not on this list, assume you cannot call it until you have opted in.
| Tool | What It Does |
|---|---|
twining_assemble |
Gate 1: Build tailored context for a task — decisions, warnings, handoffs, within a token budget |
twining_record |
Gate 2: Record what you did and any choices made — natural language in, structured decisions out |
twining_post |
Share findings, warnings, needs, or status during work. summary is capped at 200 characters and longer summaries are rejected — put the substance in detail |
twining_resolve |
Mark open needs/questions/warnings handled. Persists status: "resolved" with resolver identity and note; the record stays on the board as searchable history. The everyday exit from the open lane (dismissal is for noise only) |
twining_why |
Check what decisions constrain a file before modifying it |
twining_status |
Health check — entry counts, decision counts, actionable warnings |
twining_housekeeping |
Periodic maintenance — deduplicate, surface stale decisions, prune, rotate (dry-run by default). The board-archive pass is opt-in (archive: true) and retains the newest archive.retain_recent entries. Optional staleness_review, merge_sweep, and compact_archives flags |
twining_archive |
Move blackboard entries to the archive tier. Takes no cutoff by default — an argument-free call archives everything archivable, so pass before or retain (keep newest N) unless you intend a full sweep |
twining_archive_stale |
Archive caller-confirmed candidate IDs from staleness or merge-sweep review. Decisions move to archived status; entries are dismissed. Provenance preserved. Warns on batches above 5% of live decisions |
twining_unarchive |
Restore archived decisions to active — the undo for a bad archive sweep. Assemble/why report hidden archived decisions as archived_excluded_count |
twining_add_entity |
Add a knowledge-graph entity |
twining_add_relation |
Add a knowledge-graph relation |
twining_neighbors |
Traverse the graph from an entity |
twining_graph_query |
Query graph entities and relations |
twining_prune_graph |
Remove stale graph nodes |
twining_record accepts natural language decisions like "Chose Redis over Memcached — need persistence" and automatically parses them into structured records with rationale, rejected alternatives, and inferred domain. It also accepts assumptions, constraints, affected files, and dependency chains — everything the decision store needs for high-fidelity context assembly.
Extended Tools (available with full_surface: true)
For advanced workflows — deep decision management, graph exploration, multi-agent coordination:
| Category | Tools |
|---|---|
| Decisions | twining_decide, twining_search_decisions, twining_reconsider, twining_link_commit, twining_amend, twining_trace, twining_override, twining_promote, twining_commits |
| Blackboard | twining_read, twining_query, twining_recent, twining_dismiss |
| Context | twining_summarize, twining_what_changed |
| Triage | twining_triage |
| Coordination | twining_register, twining_agents, twining_discover, twining_delegate, twining_handoff†, twining_acknowledge† |
| Lifecycle | twining_verify, twining_export |
† Deprecated in v2.0 — real handoffs happen as git-committed markdown docs; redesign or v3 removal tracked in #33.
You do not need twining_decide. It is the most commonly reached-for extended tool, but twining_record's decisions array writes to the same decision store and is available by default. twining_record also accepts commit_hash, supersedes, and depends_on, covering what twining_link_commit and twining_override do for the common cases. Reach for the extended surface when you need decision archaeology (trace, search_decisions) or the provisional ratification lifecycle — not for ordinary recording.
Enable with .twining/config.yml:
tools:
full_surface: true
Twining MCP questions
What tools does Twining MCP provide?
It exposes 15 tools, including twining_assemble, twining_record, twining_post, twining_resolve, twining_why.
How does Twining differ from CLAUDE.md?
CLAUDE.md is a static file for standing instructions, whereas Twining is dynamic, capturing decisions, rationale, and rejected alternatives as they happen.
How is Twining different from an orchestrator?
While orchestrators route work by assigning tasks, Twining coordinates by sharing state through a blackboard that persists outside an agent's context window.
Can I use Twining with clients other than Claude Code?
Yes, you can install it for non-Claude-Code clients like Cursor or Windsurf using the MCP-only installation method.