[FEATURE] Implement Claude Memory Api with Basic Memory

[phernandez]

Feature Description

Anthropic recently released a memory tool for Claude that enables storing and retrieving information across conversations using client-side file operations. This validates Basic Memory's local-first, file-based architecture - Anthropic converged on the same pattern.

However, Anthropic's memory tool is only available via their API and stores plain text. Basic Memory can offer a superior implementation through MCP that:

1. Works everywhere - Claude Desktop, Code, VS Code, Cursor via MCP (not just API)
2. Structured knowledge - Entities with observations/relations vs plain text
3. Full search - Full-text search, graph traversal, time-aware queries
4. Unified storage - Agent memories + user notes in one knowledge graph
5. Existing infrastructure - Leverages SQLite indexing, sync, multi-project support

This would enable AI agents to store contextual memories alongside user notes, with all the power of Basic Memory's knowledge graph features.

What

Create a new MCP tool memory that matches Anthropic's tool interface exactly, allowing Claude to use it with zero learning curve. The tool will store files in Basic Memory's /memories directory and support Basic Memory's structured markdown format in the file content.

See SPEC-18

References

• Anthropic Memory Tool: https://docs.claude.com/en/docs/agents-and-tools/tool-use/memory-tool
• Anthropic Blog: https://www.anthropic.com/news/context-management
• Python SDK Example: https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py
• Memory Cookbook: https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/memory_cookbook.ipynb

[claude]

Claude finished @phernandez's task —— View job

---

Issue #373 Triage Analysis

Todo List

• Read SPEC-18 specification
• Classify issue type, priority, component, and complexity
• Search for duplicate issues
• Apply appropriate GitHub labels
• Provide triage analysis

---

Classification

Type: Feature Request (Enhancement)

• New MCP tool implementation with existing specification (SPEC-18)
• Integrates Anthropic's memory tool interface with Basic Memory's knowledge graph

Priority: High

• Validates Basic Memory's architecture (Anthropic converged on same pattern)
• High strategic value: positions BM as superior to Anthropic's API-only tool
• Enables AI agents to store structured memories alongside user notes
• Zero learning curve for Claude (already trained on memory interface)

Component: MCP Tools

• Primary: New MCP tool (src/basic_memory/mcp/tools/memory_tool.py)
• Secondary: Project management (dedicated "memories" project)
• Integration: Sync service, search, knowledge graph

Complexity: Medium-High

• Well-defined specification with clear requirements
• 6 commands to implement (view, create, str_replace, insert, delete, rename)
• Requires dedicated project management and path security
• Significant test coverage needed (unit + integration)
• Documentation and prompting system required

Analysis

What Makes This Important:

1. Strategic Validation - Anthropic's release of a memory tool validates BM's local-first, file-based architecture. They independently converged on the same pattern.

2. Competitive Advantage - BM can offer superior implementation:

   • Works everywhere via MCP (not just API)
   • Structured knowledge (entities/observations/relations vs plain text)
   • Full-text search and graph traversal
   • Unified storage with existing notes

3. Zero Learning Curve - Exact interface match with Anthropic's tool means Claude already knows how to use it

4. Architectural Fit - Leverages existing infrastructure:

   • SQLite indexing
   • Sync service
   • Multi-project support
   • Knowledge graph capabilities

Implementation Scope:

From SPEC-18, this requires:

• New MCP tool with 6 commands (matches Anthropic interface exactly)
• Dedicated "memories" Basic Memory project (isolated from user notes)
• Folder structure: user/, projects/, sessions/, patterns/
• Path security using pathlib (prevent directory traversal)
• Error handling matching Anthropic's patterns
• Automatic system prompt guidance
• Optional memory_guide MCP prompt
• Comprehensive test coverage
• Documentation updates

No Duplicates Found - Search returned this issue (#373) plus unrelated features

Recommendation

This is a high-value feature that should be prioritized for implementation. The specification is thorough and well-reasoned, with clear success criteria. The feature validates BM's architecture while providing competitive differentiation.

Estimated Effort: 3-5 days for full implementation including:

• Core tool implementation
• Dedicated project setup
• Path validation and security
• Error handling
• Test coverage (unit + integration)
• Prompting system
• Documentation

Label Applied: enhancement

--- | Branch: claude/issue-373-20251016-2002