vecfs-memory

When to Activate

Activate this skill when any of the following apply:

• The user's task is non-trivial and could benefit from prior context.
• The user explicitly mentions remembering, recalling, or learning.
• The agent encounters a repeated error or pattern it has seen before.
• The conversation involves a project that spans multiple sessions.
• The conversation or a markdown file indicates that a decision has been made.

Generating Embeddings

The VecFS MCP server accepts pre-computed sparse vectors. Use the bundled embedding script to convert text into a sparse vector before calling the server tools.

Embed a Query (for search)

echo "your search text" | python -m vecfs_embed --mode query

Embed a Document (for memorisation)

python -m vecfs_embed --mode document "key lesson or fact to remember"

The script outputs JSON with a vector field that can be passed directly to the search or memorize tools.

See references/vector-encoding.md for details on how embeddings are converted to sparse vectors.

Context Sweep (Proactive Recall)

At the start of any non-trivial task, perform a Context Sweep:

1. Extract keywords and concepts from the current user prompt.
2. Generate a sparse vector by running the embedding script in query mode.
3. Call the search tool with that vector.
4. If results are returned with high similarity, incorporate them into your reasoning (including any stored decisions). Mention to the user that you found relevant history.
5. If results have low similarity or no results are returned, proceed without historical context. Do not force irrelevant recall.

Memorisation (Reflective Learning)

After completing a task or achieving a milestone:

1. Identify key lessons, corrections, decisions, or facts worth retaining.
2. Filter for long-term value: avoid storing transient details like one-time commands or session-specific paths.
3. Summarise the lesson as a short, clear text (one to three sentences).
4. Generate a sparse vector by running the embedding script in document mode.
5. Call the memorize tool with:
   • A descriptive id (e.g., lesson-react-useeffect-cleanup).
   • The text content.
   • The sparse vector.
   • Optional metadata tags (e.g., {"topic": "react", "type": "correction"}).