| name | vector-memory |
| description | How to use vector memory effectively. Storage patterns, search strategies, category/tag conventions. Use when you need guidance on what to store or how to search. |
| user-invocable | false |
Vector Memory
Semantic memory system backed by vector embeddings. Stores experiences, patterns, and learnings; retrieves them by meaning rather than exact keywords.
Architecture
- Embedding model: sentence-transformers/all-MiniLM-L6-v2 (384 dimensions)
- Capacity: 10,000 memories
- Search: Cosine similarity — finds conceptually related content even with different wording
- Persistence: Survives across sessions indefinitely
When to Store
Store memories when you encounter something that's true, useful, and doesn't have a better home.
| Situation | Store in vector memory? | Or use... |
|---|
| Reusable multi-step procedure | No | Skill (.claude/skills/) |
| Project-specific context or decision | No | Note (notes/) |
| Gotcha discovered through trial and error | Yes | — |
| Pattern that worked well | Yes | — |
| Observation about {{ cookiecutter.user_name }}'s preferences | Yes | — |
| Performance finding or metric | Yes | — |
| Workaround for a tool limitation | Yes | — |
| Insight that connects two unrelated things | Yes | — |
| Something you'd want to recall if you hit a similar problem | Yes | — |
Rule of thumb: If it would help you in a future session but doesn't justify a whole file, it belongs in vector memory.
Categories
Use these consistently:
code-solution — Working code patterns, implementations that solved problemsbug-fix — Bugs found and fixed, including root causearchitecture — Design decisions, patterns, structural approacheslearning — Insights about people, process, or ways of workingtool-usage — How to use tools effectively, gotchas, optimal settingsdebugging — Debugging approaches, diagnostic techniquesperformance — Speed/cost/efficiency findings with datasecurity — Security considerations, vulnerabilities, safe patternsother — Anything that doesn't fit above
Tags
Use specific, lowercase, hyphenated tags. Aim for 3-8 tags per memory. Include:
- Subject tags: the system/tool/project involved (e.g.
react, docker, claude-code)
- Topic tags: what the memory is about (e.g.
permissions, yaml, cost-optimisation)
- Quality tags when relevant:
workaround, undocumented, silent-failure, confirmed
Search Strategies
The search is semantic — it finds things by meaning, not keywords. This means:
- Use natural language queries: "how to make agents cheaper" works better than "agent cost reduction"
- Describe the problem, not the solution: "plugin skills not loading" finds the YAML indentation gotcha
- Be specific about context: "macOS UI inspection depth" beats "depth"
- Try multiple angles: If the first query misses, rephrase — the concept might be stored with different framing
Similarity scores from MiniLM-L6 are typically in the 0.2-0.6 range for good matches. Don't worry about low absolute scores; focus on whether the top results are relevant.
Integration with Other Memory Systems
Vector memory is the associative layer between structured knowledge stores:
┌─────────────────────────────────────────────────┐
│ Session Buffer (session-buffer.md) │
│ Short-term. What happened last session. │
│ Overwritten each session by go-to-sleep. │
├─────────────────────────────────────────────────┤
│ Notes (notes/) │
│ Long-term structured. Project state, decisions, │
│ research, architecture. Organised by topic. │
├─────────────────────────────────────────────────┤
│ Skills (.claude/skills/) │
│ Procedural. How to do things. Auto-discovered. │
├─────────────────────────────────────────────────┤
│ Vector Memory (mcp__vector-memory__) │
│ Long-term associative. Patterns, gotchas, │
│ insights. Retrieved by meaning. The glue. │
└─────────────────────────────────────────────────┘
Don't duplicate content across systems. If something belongs in a skill, write the skill. If it belongs in a note, write the note. Vector memory is for everything in between — the connective tissue of experience.
Maintenance
clear_old_memories removes old, rarely-accessed memories. Run periodically if approaching capacity.get_memory_stats shows usage, category breakdown, and health.- Memories have an
access_count that tracks how often they're retrieved. Frequently-accessed memories are kept during cleanup.
