feat(memory): AutoMemoryBridge - Claude Code Auto Memory Integration (ADR-048)
- Dominant language
- TypeScript
- Stars
- 72.7k
- Forks
- 8.6k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 83
Description
## Summary
Implements bidirectional sync between Claude Code's [auto memory](https://code.claude.com/docs/en/memory) and claude-flow's AgentDB + HNSW memory system.
Auto memory is a persistent directory (`~/.claude/projects//memory/`) where Claude writes learnings as markdown. `MEMORY.md` (first 200 lines) loads into the system prompt; topic files are read on demand.
## What's Implemented (Phase 1)
### AutoMemoryBridge Service
- **Source**: `v3/@claude-flow/memory/src/auto-memory-bridge.ts` (~883 lines)
- **Tests**: `v3/@claude-flow/memory/src/auto-memory-bridge.test.ts` (58 tests, 291ms)
- **ADR**: `v3/implementation/adrs/ADR-048-auto-memory-integration.md`
### Core API
- `recordInsight()` - Store insight in AgentDB + write to topic files
- `syncToAutoMemory()` - Flush buffered insights, query AgentDB for high-confidence entries
- `importFromAutoMemory()` - Import markdown files into AgentDB with batch insert
- `curateIndex()` - Regenerate MEMORY.md, keep under 200-line limit
- `getStatus()` - Report directory info, file counts, buffer state
### Utility Functions (all exported)
- `resolveAutoMemoryDir()` - Derive auto memory path from git root
- `findGitRoot()` - Walk up filesystem to find `.git`
- `parseMarkdownEntries()` - Parse `##` headings into structured entries
- `extractSummaries()` - Extract bullet summaries, strip metadata annotations
- `formatInsightLine()` - Format insight as markdown bullet with metadata
- `hashContent()` - SHA-256 truncated to 16 hex for dedup
- `pruneTopicFile()` - Keep topic files under line limit
- `hasSummaryLine()` - Exact bullet-prefix dedup check
### Configuration
- **Sync modes**: `on-write`, `on-session-end`, `periodic`
- **Prune strategies**: `confidence-weighted`, `fifo`, `lru`
- **7 insight categories**: project-patterns, debugging, architecture, performance, security, preferences, swarm-results
### Optimizations Applied
- Static import of `createDefaultEntry` (was dynamic `await import()` per call)
- `syncedInsightKeys` Set prevents double-write race condition
- `node:fs/promises` for async I/O on write paths
- `fetchExistingContentHashes()` single-query batch lookup (replaces N individual queries)
- `bulkInsert()` for batch importing
- `pruneSectionsToFit()` prunes before index build (eliminates O(n^2) rebuild)
- `hasSummaryLine()` exact bullet-prefix matching (not substring `includes()`)
- `extractSummaries()` strips `_(source, date, conf)_` metadata annotations
## Remaining Work (Phases 2-4)
### Phase 2: Hooks Integration
- [ ] Wire `session-end` hook to trigger `syncToAutoMemory()`
- [ ] Wire `session-start` hook to trigger `importFromAutoMemory()`
- [ ] Wire `post-task` hook for insight recording
- [ ] Integration tests with mock hook context
### Phase 3: CLI & MCP
- [ ] `memory sync-auto` CLI command
- [ ] `memory import-auto` CLI command
- [ ] `memory auto-status` CLI command
- [ ] MCP tools: `memory_auto_sync`, `memory_auto_record`
### Phase 4: Swarm Integration
- [ ] Swarm result → auto memory pipeline
- [ ] Semantic deduplication for swarm learnings
- [ ] Dashboard/status for auto memory health
## Related
- ADR-048: Auto Memory Integration
- ADR-006: Unified Memory Service
- ADR-018: Claude Code Deep Integration
Contributor guide
Research direction
Start with v3/@claude-flow/memory/src/auto-memory-bridge.ts, its 58-test suite, and ADR-048. Review the existing Phase 1 API before investigating the session-end, session-start, and post-task hook entry points, then examine the CLI and MCP integration areas. Done means the selected Phase 2–4 workflows are wired, tested with the stated mock hook context where applicable, and preserve the documented sync and pruning behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- ai, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100