Claude Code memory integration: BM as complementary knowledge graph layer

[phernandez]

Context

Claude Code has a built-in file-based memory system that writes markdown files with YAML frontmatter to .claude/projects/.../memory/. It maintains a MEMORY.md index and supports memory types (user, feedback, project, reference). This system works well for what it does.

Basic Memory's strength is turning markdown files into a knowledge graph with semantic search, relations, and cross-note navigation. These capabilities would complement Claude Code's memory without replacing it.

Idea

Make Basic Memory a complementary layer around Claude Code's native memory — similar to how OpenClaw's memory-wiki plugin augments rather than replaces the existing memory flow.

What this adds

Claude Code's memory alone:

• File-based markdown with frontmatter
• Filename/keyword matching
• Manual MEMORY.md index
• Flat structure, no connections between memories

With BM as a complementary layer:

• Semantic search across memories ("what do I know about indexing performance?")
• Knowledge graph — relations between memories emerge automatically
• memory:// URL navigation via build_context
• Cross-session context — richer retrieval than scanning MEMORY.md
• Visualization in Obsidian/canvas

Implementation options

1. Passive index: BM watches the memory directory as a project, indexes files as Claude Code writes them. Zero changes to Claude Code's behavior. BM adds search/graph on top.

2. Hook-based sync: Claude Code hook triggers bm sync after memory file writes. Same passive approach but with immediate indexing.

3. Dual-write: Claude Code instructions updated to also call BM MCP tools (write_note, build_context) alongside file writes. Richer integration but requires instruction changes.

4. Native plugin: BM ships as a Claude Code skill or MCP server that the memory system calls into directly. Deepest integration.

Design principle

Don't get in the way of the memory flow. Complement it. The user shouldn't have to remember anything special or change their workflow. BM just makes the memories more useful.

Prior art

• OpenClaw memory-wiki plugin
• Claude Code's auto-memory system (file-based, .claude/projects/.../memory/)

[claude]

Claude finished @phernandez's task in 1m 27s —— View job

---

Triage Analysis

• Read and understand the issue
• Check for duplicate issues
• Classify issue type, priority, component, complexity
• Apply labels
• Provide analysis and response

---

Classification

Dimension	Value
Type	Feature request
Priority	Medium
Component	MCP, CLI
Complexity	Complex

Labels applied: enhancement

---

Duplicate / Related Issue Check

No duplicates found, but two closely related issues exist:

• Feature: Coding agent sidecar — watch session transcripts, build knowledge graph #669 — Coding agent sidecar: Proposes a file-watcher sidecar that reads Claude Code session transcripts (~/.claude/projects/*/sessions/) and builds a knowledge graph from them. This overlaps significantly with Options 1 and 2 here.
• Consolidate plugins & skills into main repo + build Codex plugin #699 — Consolidate plugins & skills: Proposes merging basic-memory-skills and basic-memory-plugins into the main repo, including a Claude Code plugin. Directly relates to Option 4 (native plugin).

This issue is complementary to both — it focuses specifically on the memory directory (.claude/projects/.../memory/) rather than session transcripts, and on augmenting Claude Code's native memory with BM's knowledge graph capabilities.

---

Analysis

This is a well-considered feature proposal. A few thoughts on each implementation option:

Option 1 — Passive index (recommended starting point)
This is the simplest and most robust approach. BM already supports watching directories as projects. Users could simply:

basic-memory project add "claude-memory" ~/.claude/projects/$(whoami)/memory/

Zero code changes needed. BM immediately adds semantic search, memory:// navigation, and knowledge graph on top of what Claude Code writes. This could be documented today as a "recipe."

Option 2 — Hook-based sync
Builds on Option 1 with a Claude Code hook to trigger immediate sync after writes. This is also achievable today via Claude Code's PostToolUse hook pointing at basic-memory sync. Worth documenting alongside Option 1.

Option 3 — Dual-write
The current auto-memory system in Claude Code (which this very repo uses, per the system prompt) already writes to the memory directory. Updating the instructions to also call write_note would make BM a first-class citizen. This is the richest integration but requires Claude Code instruction changes — the kind of thing that could live in a CLAUDE.md skill or the Claude Code plugin from #699.

Option 4 — Native plugin
This is the most complete but most effort — essentially what #699 is building. The Claude Code plugin (basic-memory-plugins) would be the delivery vehicle.

Recommended Path

1. Short-term (no code changes): Document Options 1 & 2 as a "recipe" in the docs — this provides immediate value and validates the concept.
2. Medium-term: Add Option 3 to the Claude Code plugin being consolidated in Consolidate plugins & skills into main repo + build Codex plugin #699.
3. Long-term: Option 4 follows naturally from Consolidate plugins & skills into main repo + build Codex plugin #699's consolidation work.

The guiding principle in the issue ("don't get in the way of the memory flow") is exactly right. Option 1 is the purest expression of that.