Skip to main content

Memory bank and MCP

The memory bank is an external archive of feature artifacts. Instead of leaving features/{slug}/ inside each product repo, you link a separate git folder, index it with SQLite FTS5, and let the agent search past requests, decisions and handoffs.

:::note Not the wiki The Wiki holds short reusable lessons inside .pipeline/wiki/. The memory bank holds the artifacts of every feature (requests, architecture, decisions, handoffs), usually in a shared repo. They are separate and do not overlap. :::

Steps​

  1. When to use it
  2. Install the extra — same CLI as pipeline-kit
  3. Set up a product — link → index → search
  4. Register the MCP server (optional)
  5. Tools
  6. Troubleshooting

When to use it​

  • A product line spans several repos and you want one shared archive.
  • You want an org-wide record of past decisions that agents can query.
  • You do not want artifacts committed to the product repo.

If you have a single repo and are happy with features/{slug}/ in it, you do not need this.

Install the extra​

It is optional and free (Licensing). pipeline-kit init does not install it.

pipeline-kit memory --help only parses flags. Real commands import pipeline_memory from the same environment as the CLI. If you installed pipeline-kit with uv tool / ./install.sh, add the extra with uv tool from the kit checkout — not pip into another Python.

cd /path/to/pipeline-kit-checkout
uv tool install -e ".[memory]"
pipeline-kit memory doctor .

That is the same pattern as .[orchestrator] and .[assess]. This adds pipeline-kit memory ... and the pipeline-memory-mcp server binary.

doctor / status can still exit 1 until you memory link. The line pipeline-kit-memory is not installed must be gone.

If the kit is an editable install in the same venv as the CLI, pip install -e packages/pipeline-kit-memory -e . is an alternative.

Set up a product​

Run from the product root (it must already have .pipeline/):

pipeline-kit memory link ../pipeline-memory --project-id my-app
pipeline-kit memory import-local # one-time copy of existing features/
pipeline-kit memory index
pipeline-kit memory search "oauth decision" --json
pipeline-kit memory doctor

link writes a memory block into .pipeline/config.json. Indexing is required before search returns anything, and you must re-run memory index after artifacts change. The MCP server does not re-index on its own.

Layout​

ModePath in the bank
Flat (one product, one bank){root}/features/{slug}/...
Namespaced (--project-id){root}/projects/{id}/features/{slug}/...

Run state (.pipeline/state/) always stays in the product project. The index lives at {root}/.memory/index.sqlite and is gitignored in the bank.

Register the MCP server​

The kit does not wire memory into your IDE. Each developer (or a team template) adds a stdio MCP entry, then restarts the client. The client spawns the server when a tool is called, so you never keep it running in a terminal.

--project must be the absolute path of the product repo you linked (the one containing .pipeline/config.json), not the bank folder.

Cursor (.cursor/mcp.json):

{
"mcpServers": {
"pipeline-memory": {
"command": "pipeline-memory-mcp",
"args": ["--project", "C:/path/to/your-product-repo"]
}
}
}

VS Code / Copilot (mcp.json; the key may be servers):

{
"servers": {
"pipeline-memory": {
"type": "stdio",
"command": "pipeline-memory-mcp",
"args": ["--project", "C:/path/to/your-product-repo"]
}
}
}

Claude Desktop (claude_desktop_config.json) uses the same shape as Cursor. Claude Code and other stdio hosts work the same way.

If pipeline-memory-mcp is not on PATH, set command to your full python.exe path and use args -m, pipeline_memory.mcp_server, --project, <product path>.

Tools​

ToolArgumentsPurpose
memory_searchquery, optional slug, kind, limitFull-text search over indexed chunks
memory_whyquery, optional slug, limitPrefers decision, request, handoff and architecture docs
memory_getpath, or slug + relRead one artifact file
memory_list_slugsnoneList feature slugs in the bank
memory_list_filesslugList files under one feature

The server is read-only. Changes to the bank go through normal git plus memory index.

To verify, restart the IDE, call memory_list_slugs, then memory_search with { "query": "architecture", "limit": 5 }.

Troubleshooting​

SymptomFix
Command not foundUse the full path to pipeline-memory-mcp or python.exe, from the env where you ran uv tool install -e ".[memory]"
--help works, status/doctor say not installedExtra is in a different Python than the CLI. Re-run uv tool install -e ".[memory]" from the kit checkout
Tools missing in the IDEInvalid JSON or wrong file location. Restart the client and check MCP logs
memory not enabledRun memory link and check memory.enabled and memory.root in .pipeline/config.json
Search always emptyRun pipeline-kit memory index ., then try memory_list_slugs first
Results from the wrong project--project points at another repo. Fix the absolute path

CLI commands are listed in the CLI reference. The package README at packages/pipeline-kit-memory/README.md has the full detail.