feat(mcp): Add multi-bank access and new MCP tools

[bjornslib]

Summary

Enables orchestrator agents to access multiple memory banks from a single MCP connection, with new tools for bank management.

New MCP Tools

Tool	Purpose
reflect(query, context?, budget?, bank_id?)	Thoughtful analysis using bank's personality and memories
list_banks()	Discover all available memory banks
create_bank(bank_id, name?, background?)	Create new banks programmatically

Multi-Bank Access

Added optional bank_id parameter to existing tools:

• retain(content, context, bank_id?) - Store in specific bank
• recall(query, max_results?, bank_id?) - Search specific bank
• reflect(query, context?, budget?, bank_id?) - Reflect using specific bank

When bank_id is not specified, the session's default bank is used.

Claude Code Compatibility

• Enabled stateless_http=True for proper Claude Code integration
• Responses now include bank_id for transparency

Documentation

• Added docker-compose.example.yml with env var substitution (no secrets)
• Added HINDSIGHT-DOCKER.md setup guide with volume persistence warnings
• Updated .gitignore to exclude local docker-compose.yml

Use Case

Orchestrator agents managing multiple Claude Code instances can now:

• Maintain a private meta-orchestration bank for self-reflection
• Access shared project knowledge banks
• Query across banks for cross-context insights

Example:

# Store in specific bank
retain(content="Learned pattern", bank_id="orchestrator-memory")

# Reflect using orchestrator's personality
reflect(query="What patterns work?", bank_id="orchestrator-memory")

[bjornslib]

• Adding reflection as a MCP tool was essential to enable Claude Code to reflect on its behaviour and use it to consider potential solution design options, next steps and good patterns.
• Having the ability to utilise bank_id, but keeping it as an optional parameter, is handy when using multiple memory banks from within the same Claude Code. I understand that it was a design choice to use the URL's with /memory_bank_id yet that requires having multiple MCP tools in-context, which isn't optimal.
• The stateless_http=True is something that Claude Code prefers.

[nicoloboschi]

please remove this file, we don't want to keep a docker compose for a simple installation. everything should be in the doc and if something missing you can add there

[nicoloboschi]

please remove this file, we don't want to keep a docker compose for a simple installation. everything should be in the doc and if something missing you can add there

[nicoloboschi]

I don't think this is clear enough for the agent to understand what do to with it. have you tried it out already?

initalliy this was the only implementation but I had issues letting Claude to understand the bank_id param and what to use exactly. and when it gets confused by a tool usually it just ignores it

[bjornslib]

You're right it should include a better tool description. Let me work on that. It works for me locally because I created a skill that uses Hindsight and it describes how to use it.

[bjornslib]

@nicoloboschi this has been updated. I'm not 100% certain if the reflect tool description reflects (pun intended) how you are recommending people use it. But it's how I've used it in my agent setup. Let me know if you'd like me to make any more tweaks!