Skip to content
Skills Library
AI & agents · Learning & explanation

vector-memory-usage

/vector-memory-usage

This skill should be used when the user asks to "store a memory", "remember this", "search memories", "what did we decide", "find relevant context", "update a memory", "delete a memory", "that memory was useful", discusses "memory quality", "memory best practices", "proactive memory search", or when guidance is needed on when and how to use the vector memory system effectively. Provides patterns for storing, searching, and leveraging semantic memories across sessions.

Licence
MIT
Last repository change
16.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 16.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

This skill should be used when the user asks to "store a memory", "remember this", "search memories", "what did we decide", "find relevant context", "update a memory", "delete a memory", "that memory was useful", discusses "memory quality", "memory best practices", "proactive memory search", or when guidance is needed on when and how to use the vector memory system effectively. Provides patterns for storing, searching, and leveraging semantic memories across sessions.

Triggers from the description

store a memoryremember thissearch memorieswhat did we decidefind relevant contextupdate a memorydelete a memorythat memory was useful
Original author description

This skill should be used when the user asks to "store a memory", "remember this", "search memories", "what did we decide", "find relevant context", "update a memory", "delete a memory", "that memory was useful", discusses "memory quality", "memory best practices", "proactive memory search", or when guidance is needed on when and how to use the vector memory system effectively. Provides patterns for storing, searching, and leveraging semantic memories across sessions.

How it works

  1. Global Storage Model
  2. When to Proactively Search Memories
  3. Writing Effective Search Queries
  4. Storing High-Quality Memories
  5. Updating and Deleting Memories
  6. Memory Usefulness Feedback
  7. Tools Reference
Original SKILL.md headings · 198 lines, 1,434 words
SKILL.md preview
---
name: vector-memory-usage
description: This skill should be used when the user asks to "store a memory", "remember this", "search memories", "what did we decide", "find relevant context", "update a memory", "delete a memory", "that memory was useful", discusses "memory quality", "memory best practices", "proactive memory search", or when guidance is needed on when and how to use the vector memory system effectively. Provides patterns for storing, searching, and leveraging semantic memories across sessions.
---

# Vector Memory Usage

The vector memory system provides semantic memory storage shared across every project. Memories persist across sessions and are retrieved via semantic search — meaning queries find relevant memories by meaning, not just keyword matching.

## Global Storage Model

The vector-memory MCP server stores all memories in a single global SQLite database (`~/.vector-memory/memories.db`), shared by every project on the machine. Each memory is automatically tagged with the project (the working directory) it was stored from — no per-repo database, nothing to commit to version control.

- **Storing:** memories are stamped with the current project automatically. Only pass an explicit `project` to file a memory under a different project.
- **Searching:** by default, search covers all projects; results from the current project rank slightly higher, and every result carries its project path. Pass `scope: "project"` when the query is clearly specific to the current repo (cuts cross-project noise), or an explicit project path to search another repo's memories.
- **Migrating:** repos with a legacy `.vector-memory/` directory can be imported into the global store with `bunx @aeriondyseti/vector-memory-mcp consolidate` (see the README). If a repo still has `.vector-memory/` in version control, remove it and add `.vector-memory/` to `.gitignore`.

A repo-local database is still available via `--db-file` or `VECTOR_MEMORY_DB_PATH` for special cases.

## When to Proactively Search Memories

Search memories BEFORE making decisions or assumptions. The cost of an unnecessary search is low; the cost of missing relevant context is high.

### Mandatory Search Triggers

- **Architectural decisions** — before choosing a library, pattern, or approach, search for prior decisions on the same topic
- **Debugging unfamiliar code** — search for implementation notes, known issues, or past resolutions
- **Starting a new task** — search for relevant context, prior attempts, or related decisions
- **Referential ambiguity** — when the user says "the project", "that bug", "last time", "as we discussed", search to resolve the reference
- **Repeated patterns** — when implementing something similar to past work, search for the established pattern

### Recommended Search Triggers

- **Before suggesting solutions** — check if the problem was solved before
- **When encountering unfamiliar conventions** — search for project-specific patterns or standards
- **Code review context** — search for why code was written a certain way before suggesting changes
- **Configuration questions** — search for prior setup decisions and rationale

## Writing Effective Search Queries

### Use Natural Language with Keywords

Good queries combine intent with specific terms:

| Scenario | Query | Intent |
|----------|-------|--------|
| Resuming work | "authentication system architecture" | `continuity` |
| Checking a decision | "database choice PostgreSQL vs SQLite" | `fact_check` |
| Finding patterns | "error handling patterns API endpoints" | `frequent` |
| Exploring connections | "performance optimization caching" | `associative` |
| Creative exploration | "alternative approaches to state management" | `explore` |

### Search Intents

Call `mcp__vector-memory__search_memories` with the appropriate intent:

- **continuity** — resuming work, finding recent context (favors recency)
- **fact_check** — verifying decisions or specifications (favors relevance)
- **frequent** — finding common patterns or preferences (favors utility)
- **associative** — brainstorming, finding connections (high relevance + variety)
- **explore** — stuck or creative mode (balanced + diverse results)

### Always Provide a Reason

The `reason_for_search` field forces intentional retrieval. Be specific:
- "Checking if there's a prior decision on auth approach before suggesting JWT"
- "Looking for known issues with the payment module before debugging"

## Storing High-Quality Memories

### One Concept Per Memory

Each memory should be self-contained and capture exactly one idea:

**Good:**
```text
"Chose libSQL over PostgreSQL for the Resonance project because
of native vector support and simpler single-file deployment for local-first
architecture."
```

**Bad:**
```text
"Uses SQLite"
```

The good example includes: what was decided, for which project, and why. The bad example lacks context, subject, and reasoning.

### Memory Content Rules

- **1-3 sentences** (20-75 words) per memory
- **Self-contained** — use explicit subjects, never "it", "this", "the project"
- **Include dates/versions** when relevant
- **Be concrete** — specific file paths, tool names, version numbers

### Using embedding_text for Long Content

When memory content exceeds ~1,000 characters, provide an `embedding_text` field with a concise searchable summary. The embedding is generated from `embedding_text` instead of the full content, ensuring the memory remains discoverable:

```json
{
  "content": "[detailed multi-paragraph implementation notes...]",
  "embedding_text": "Authentication middleware implementation using JWT with RS256 signing and refresh token rotation",
  "metadata": { "type": "implementation" }
}
```

### Naming Where a Memory Belongs (context)

When a memory comes from a larger source — a document, a note, a long discussion — give its `context`: a short path from the source to the section. It is searched with the memory (and weighted above its words), so the memory is found by what it belongs to even when its own text doesn't name it:

```json
{
  "content": "Refresh tokens rotate on every use; a reused token revokes the whole family.",
  "context": "Atlas design doc > Auth flow > Refresh tokens"
}
```

Use the same names the source uses (document title, section headings, a character's or project's name) so lookups by those names find it.

### Storing Syntheses (sources)

When you answer a broad question by pulling several memories together — a summary of how something developed, a pattern across sessions, a conclusion — store that answer as its own memory and list the memories it draws on in `sources`. The next broad question finds the synthesis directly instead of rebuilding it, and search flags it if a source is later replaced or deleted:

```json
{
  "content": "Across the last five sessions the envoy has lied to the party three times, always about the treaty terms.",
  "sources": ["<memory id>", "<memory id>", "<memory id>"]
}
```

### What to Store

Call `mcp__vector-memory__store_memories` with appropriate metadata type tags:

| Type | Store | Example |
|------|-------|---------|
| `decision` | What was chosen + why | "Chose Drizzle ORM over Prisma for type safety and SQL-like syntax" |
| `implementation` | What was built + where + patterns | "Auth middleware in src/middleware/auth.ts uses JWT with RS256 signing" |
| `insight` | Learning + why it matters | "sqlite-vec virtual tables require DELETE+INSERT, not INSERT OR REPLACE" |
| `blocker` | Problem + resolution | "CORS errors resolved by adding origin whitelist in server config" |
| `next-step` | TODO + suggested approach | "Add rate limiting to API; consider express-rate-limit middleware" |
| `context` | Background info + constraints | "Project targets Node 20+ only; can use native fetch and crypto" |

### What NOT to Store

- Machine-specific paths or local environment details
- Ephemeral states ("tests are currently failing")
- Information easily discoverable from code
- Pleasantries or conversational filler
- Duplicate information already in existing memories

## Updating and Deleting Memories

### When to Update

Call `mcp__vector-memory__update_memories` when a memory's content is still conceptually valid but needs correction or refinement:

- A decision's rationale needs clarification
- An implementation detail changed (new file path, different approach)
- A version number or date needs updating
- The embedding_text should be improved for better search discoverability

Updating preserves the memory ID, so any waypoint references to it remain valid.

### When to Delete

Call `mcp__vector-memory__delete_memories` when a memory is no longer relevant:

- A decision was reversed entirely
- A feature was removed from the codebase
- Information is outdated and misleading
- A duplicate was accidentally created

Deletion is a soft-delete — the memory can be recovered by searching with `include_deleted: true`. This means it is safe to delete aggressively when memories become stale.

**Rule of thumb:** If the memory needs minor corrections, update it. If it no longer reflects reality, delete it.

## Memory Usefulness Feedback

Call `mcp__vector-memory__report_memory_usefulness` after retrieving memories to indicate whether they were helpful. This feedback loop is important for search quality:

- **Report useful** when a memory directly informed a decision, resolved ambiguity, or saved time
- **Report not useful** when a memory was irrelevant to the query, outdated, or misleading
- Reporting consistently helps the system learn which memory patterns provide value
- Skipping reports means the system cannot improve its ranking over time

## Tools Reference

All tools use the `mcp__vector-memory__` prefix:

| Tool | Purpose |
|------|---------|
| `mcp__vector-memory__search_memories` | Semantic search with intent-based ranking |
| `mcp__vector-memory__store_memories` | Persist new memories (batch supported) |
| `mcp__vector-memory__get_memories` | Retrieve specific memories by ID |
| `mcp__vector-memory__update_memories` | Modify existing memories in place |
| `mcp__vector-memory__delete_memories` | Soft-delete outdated memories (recoverable) |
| `mcp__vector-memory__report_memory_usefulness` | Feedback on memory quality |

For session-level snapshots, see the **waypoint-workflow** skill which covers `mcp__vector-memory__set_waypoint` and `mcp__vector-memory__get_waypoint`.

Versions

The database has no other skills named vector-memory-usage.

Database snapshot: 13.11.2026 · package version 93db05abf971 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95ai-agent-memory-systems
    Use this skill when the user says 'agent memory', 'long-term memory', 'conversation memory', 'remember user preferences', 'context window full', 'summarize history', 'episodic memory', 'semantic memory'. Designs what an agent keeps in its context window, what it stores…
  • 100memory-manager
    Local memory management for agents. Compression detection, auto-snapshots, and semantic search. Use when agents need to detect compression risk before memory loss, save context snapshots, search historical memories, or track memory usage patterns. Never lose context again.
  • 98knowledge
    Browse, search, and prune what the framework's agents remember across sessions (native agent memory under ~/.claude/agent-memory/, plus project Serena memories), and detect and migrate orphaned bare-named memory directories — use when asked "what do the agents remember", "browse…
  • 100memory-gardener
    Decide what an AI agent should remember, forget, and bring back into a new session. Use when an agent with long-term memory (a memory file, a notes folder, a vector store, CLAUDE.md-style notes) is about to save something, starts a new session and needs context, picks up…
  • 100memory
    Manage the persistent memory layer in .claude/memory/ — list, search, save, update, delete, dedupe. Use to inspect what memories exist, write a new one, or clean up stale entries.
  • 100agent-memory
    Add persistent memory to AI coding agents — file-based, vector, and semantic search memory systems that survive between sessions. Use when a user asks to "remember this", "add memory to my agent", "persist context between sessions", "build a knowledge base for my agent", "set up…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.