[feature] auto-detect and migrate existing memories on install

[ramonlimaramos]

Problem

when a user installs synapto for the first time, they likely already have memories scattered across their environment:

MCP Client	Memory location	Format
Claude Code	~/.claude/projects/*/memory/MEMORY.md	markdown with frontmatter
Claude Code	~/.claude/projects//memory/.md	individual memory files
Claude Code	~/.claude/CLAUDE.md	instructions and context
Cursor	.cursor/rules	plain text rules
Cursor	.cursorrules	legacy rules file
Windsurf	.windsurfrules	plain text rules
Codex	codex.md / AGENTS.md	markdown
Custom	various .md files	markdown

these memories are valuable — they contain project context, user preferences, workflow rules, and architectural knowledge. but after installing synapto, the user has to manually migrate them or lose the benefit of their existing memory.

Desired Behavior

during synapto init --interactive, after database setup and MCP config, synapto should:

1. scan the environment for existing memory files
2. preview what was found with counts and types
3. ask the user to confirm migration
4. import each memory with appropriate type and depth_layer
5. report what was migrated

$ synapto init --interactive

... (database, redis, embeddings setup) ...
... (mcp client config) ...

--- memory migration ---
found existing memories in your environment:

  claude code:
    ~/.claude/projects/-Users-ramon/memory/MEMORY.md (index, 12 sections)
    ~/.claude/projects/-Users-ramon/memory/feedback_readability.md (feedback)
    ~/.claude/projects/-Users-ramon/memory/reference_prod_databases.md (reference)
    ... 5 more files

  cursor:
    ~/Developer/myproject/.cursorrules (8 rules detected)

migrate these memories to synapto? [Y/n/select]:

migrating...
  [1/15] feedback_readability.md -> feedback/core
  [2/15] reference_prod_databases.md -> reference/stable
  ...

migrated 15 memories (6 feedback, 4 project, 3 reference, 2 user)

Detection Logic

claude code memories

scan ~/.claude/projects/*/memory/ for memory files. MEMORY.md is an index — parse each ## section as a separate memory. individual .md files have frontmatter with type metadata.

frontmatter parsing

claude code memory files have frontmatter:

---
name: code readability pass
description: after every implementation in divergence, do a readability pass
type: feedback
---

After completing any implementation...

synapto maps: type -> memory_type, infers depth_layer from type (feedback -> core, project -> stable, reference -> stable)

cursor/windsurf rules

split by blank lines or headings into individual rules. each rule becomes a feedback/core memory.

Import Pipeline

detect -> parse -> preview -> confirm -> embed -> store -> report
                                          |
                              entity extraction + HRR encoding

each imported memory gets:

• semantic embedding (for recall)
• entity extraction (for graph)
• HRR vector (for compositional search)
• metadata: {"source": "claude-code", "original_file": "...", "migrated_at": "..."}

Edge Cases

• duplicate detection — before importing, recall similar memories and skip if cosine similarity > 0.95
• MEMORY.md as index — parse ## sections, not the whole file as one memory
• empty files — skip silently
• re-running migration — idempotent, skip already-migrated files (check metadata.original_file)

CLI Interface

# during interactive init (automatic)
synapto init --interactive

# standalone migration command
synapto migrate scan                    # preview what would be migrated
synapto migrate run                     # execute migration
synapto migrate run --source claude     # only claude code memories
synapto migrate run --source cursor     # only cursor rules
synapto migrate run --dry-run           # preview without storing

Priority

v0.2.0 — natural companion to issue #7 (automatic memory capture). together they make synapto the complete memory solution: migrate existing + capture new.

[wazionapps]

Great feature request. Memory migration is indeed one of the hardest problems in the persistent memory space for AI coding agents.

A few observations from working on NEXO Brain, which takes a different architectural approach:

Shared brain vs per-client memory: Rather than migrating memories between clients, NEXO uses a single SQLite-backed brain that all clients (Claude Code, Codex, Claude Desktop) read from simultaneously. This eliminates the migration problem entirely — there's nothing to migrate because every client accesses the same memory store.

Format normalization: Your detection logic for different memory formats (MEMORY.md frontmatter, .cursorrules, etc.) is solid. One thing worth considering: memories have different "decay rates." A user preference (feedback/core) stays relevant for months, while a project context (project/stable) might become stale in days. If you're importing bulk memories, some kind of freshness weighting on recall would prevent old memories from overwhelming recent ones.

Deduplication at recall, not import: Your 0.95 cosine threshold for dedup at import time is reasonable, but in practice I've found it's better to allow near-duplicates in and deduplicate at recall time (return the most recent/highest-confidence match). Import-time dedup can accidentally merge memories that look similar but serve different purposes.

Entity extraction as first-class: The HRR + entity graph approach is interesting. In our implementation, the knowledge graph (entities + edges) is what provides the "oh, these two memories are actually about the same project" insight that flat semantic search misses.

Happy to discuss architectures further if useful.