Skip to main content
Glama
WazzaMo

VecFS

by WazzaMo
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

VecFS

VecFS (Vector File System) is a lightweight, local-first vector storage specification and implementation designed for AI agent long-term memory.

Copyright

(c) Copyright 2026 Warwick Molloy. Contribution to this project is supported and contributors will be recognised. Created by Warwick Molloy Feb 2026.

Overview

VecFS gives AI agents a simple, efficient way to store and retrieve context locally. Through the Model Context Protocol (MCP), agents can learn from their interactions and recall relevant information in future sessions without the complexity of a full-scale vector database.

Key Features

  • Sparse Vector Storage: Follows the principle of "not storing zeros" for natural data compression and minimal disk footprint.

  • Local-First: Designed to run on a laptop (WSL2, Linux, macOS) with simple file-based storage.

  • MCP Integration: Acts as an MCP server, providing tools for agents to search, memorize, feedback, and delete context.

  • Agent Skill: Ships with a portable Agent Skill definition that teaches agents how to use long-term memory effectively.

  • Embedding Script: Includes a model-agnostic Python tool for converting text to sparse vectors.

Quick Start

Install from GitHub (no npm or pip)

Clone the repo and run the installer. You only need Node.js and Python runtimes.

git clone https://github.com/WazzaMo/vecfs.git
cd vecfs
./install-from-github.sh

This installs into ~/.local by default. Add ~/.local/bin to your PATH if needed. For the embedding script, install Python dependencies once: pip install ~/.local/lib/vecfs/embed (or use ./install-from-github.sh --install-python-deps).

Options: --server (MCP server only), --embed (embedding script only), --prefix DIR, --install-python-deps, --help.

Related MCP server: Smriti

Install the MCP Server (npm)

npm install -g vecfs

Or run directly without installing:

npx vecfs

Agent Configuration

Add VecFS to your agent's MCP configuration (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "vecfs": {
      "command": "npx",
      "args": ["-y", "vecfs"],
      "env": {
        "VECFS_FILE": "/path/to/memory.jsonl"
      }
    }
  }
}

If you installed from GitHub with install-from-github.sh, use the full path to the binary, e.g. "command": "/home/you/.local/bin/vecfs" (and omit args), or ensure ~/.local/bin is on the PATH used by your agent.

Install the Embedding Script (pip/uv)

The embedding script converts text to sparse vectors for the MCP server.

pip install vecfs-embed

Or using uv:

uv tool install vecfs-embed

If you used the GitHub installer above, install deps from the installed copy: pip install ~/.local/lib/vecfs/embed.

Usage

# Embed a query for searching
vecfs-embed --mode query "sparse vector storage"

# Embed a document for memorisation
vecfs-embed --mode document "key lesson to remember"

# Batch embed multiple texts
cat texts.txt | vecfs-embed --batch --mode document

# Find the right sparsification threshold for your model
cat sample.txt | vecfs-embed --calibrate

Transport Modes

Stdio (Default)

vecfs

Used with CLI-based agents like Claude Desktop and Cursor. Simple, secure, no network ports exposed.

HTTP / SSE

vecfs --http
# Or with custom port
PORT=8080 vecfs --http

Used for remote agents, debugging, or containerised deployments. Endpoints: GET /sse and POST /messages.

Configuration

Environment Variable

Description

Default

VECFS_FILE

Path to the vector storage file

./vecfs-data.jsonl

PORT

Port for HTTP mode

3000

Agent Skill

VecFS ships with a vecfs-memory skill in the Agent Skills format. The skill directory is bundled in the npm package at vecfs-memory/ and teaches agents:

  • Context Sweep: Proactively search for relevant history at the start of a task.

  • Reflective Learning: Memorise key lessons after completing work.

  • Feedback Loop: Reinforce useful memories and demote unhelpful ones.

See vecfs-memory/SKILL.md for the full skill definition.

Development

Prerequisites

  • Node.js 22+ (see .node-version)

  • Python 3.10+ and uv (for the embedding script)

Building from Source

# MCP server
npm install
npm run build

# Embedding script
cd py-src
uv sync

Packaging for Distribution

To create a self-contained distributable archive containing the MCP server, the embedding script wheel, the agent skill, and an installer:

./scripts/package.sh

This runs all build steps, executes the test suites, and produces a minimal vecfs-<version>.tar.gz (~400 KB). The tarball contains no source code, no node_modules, and no dev tooling — just pre-built artefacts ready to install.

To install from the archive:

tar xzf vecfs-0.1.0.tar.gz
cd vecfs-0.1.0
./install.sh            # installs both MCP server and embedding script
./install.sh --server   # MCP server only
./install.sh --embed    # embedding script only

Running Tests

# All TypeScript tests (unit + stdio integration)
npm test

# Stdio MCP server integration tests only
npm run test:integration

# HTTP/SSE MCP server integration tests (builds first)
npm run test:http

# Python unit tests (sparsify module, no model needed)
cd py-src
uv run pytest tests/test_sparsify.py -v

# Python embedding integration tests (uses docs/ as input, loads model)
cd py-src
uv run pytest tests/test_integration.py -v

Local Agent installs

Running VecFS in Cursor

Use the package script to bundle up VecFS and use it to install the MCP server and vecfs-embed program globally.

In your local project where you want persistent memory add:

mkdir -p .cursor

create .cursor/mcp.json and give it this text.

{
  "mcpServers": {
    "vecfs": {
      "command": "npx",
      "args": ["vecfs"],
      "env": {
        "VECFS_FILE": "./vecfs-memory.jsonl",
        "PORT": "3000"
      }
    }
  }
}

Documentation

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Available Tools

4 tools
deleteB

Delete an entry from the vector space by its unique ID.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesThe unique identifier of the entry to delete.

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description only indicates a destructive action but does not disclose behavioral traits such as irreversibility, error handling on nonexistent IDs, or confirmation responses.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is extremely concise, one sentence, with no unnecessary words. It is front-loaded with the verb and resource. Could be slightly more informative without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (one parameter, no output schema, no annotations), the description is minimally adequate but lacks details on return values, error handling, or side effects. Completes the basic need but could improve.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'id'. The description redundantly states 'by its unique ID', adding no new semantics beyond the schema. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (delete) and the resource (entry from vector space) with the method (by unique ID). It distinguishes from sibling tools like feedback, memorize, and search, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. No mention of when not to delete or if there are prerequisites. The description simply states the function without usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

feedbackC

Record feedback for a specific memory entry.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
scoreAdjustmentYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It only mentions 'record,' which implies a write operation, but doesn't disclose side effects, preconditions, or whether modifications are reversible. No mention of return behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise, but it sacrifices clarity by omitting important details. It could be improved with a second sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is incomplete for a tool with 2 parameters and no output schema. It fails to explain the effect of 'scoreAdjustment', constraints, or typical usage patterns, leaving significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description does not explain any parameter. The agent must infer from parameter names ('id', 'scoreAdjustment'), which may be ambiguous (e.g., is scoreAdjustment absolute or relative?).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Record feedback') and the target ('a specific memory entry'), distinguishing it from sibling tools like delete and search. However, it does not elaborate on what constitutes feedback, leaving some ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., when to use memorize instead). The description lacks context for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memorizeA

Store a new entry in the vector space. Updates the entry if the ID already exists.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
textNo
vectorYes
metadataNo

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the upsert behavior but lacks details on authentication, rate limits, error handling, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundancy. The core purpose is front-loaded, and every word contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 parameters, nested objects, and no output schema, the description is too brief. Missing details on vector format expectations, required fields, and return behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% parameter description coverage, and the description adds little beyond naming the parameters. It does not explain the meaning or usage of 'id', 'text', 'vector', or 'metadata'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action: 'Store a new entry in the vector space' and indicates upsert behavior. It differentiates from siblings like 'delete', 'feedback', and 'search'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for storing or updating entries but does not provide explicit guidance on when to use versus alternatives or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation5/5

Each tool has a unique purpose: delete removes by ID, feedback records feedback, memorize stores/updates, and search queries by vector. There is no overlap in functionality.

Naming Consistency5/5

All tool names are lowercase verbs (delete, feedback, memorize, search), following a consistent single-word verb naming pattern.

Tool Count5/5

4 tools is perfectly scoped for a vector memory server, covering core operations (create/update, read by search, delete) plus feedback.

Completeness3/5

Covers main operations but lacks a direct retrieval tool for entries by ID; the search tool only works with vectors, so viewing a specific entry by ID is not possible.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • neuromcp

    AdelElo13
    A
    license
    Not graded
    quality
    A
    maintenance
    Semantic memory for AI agents — local-first MCP server with hybrid search, knowledge graph, contradiction detection, and plan-then-commit consolidation.
    390
    4
    AGPL 3.0

  • Smriti

    moltizmo
    A
    license
    Not graded
    quality
    D
    maintenance
    Local-first persistent memory for AI agents via MCP, enabling semantic search and memory sharing across agents with zero cloud cost and full privacy.
    16
    1
    MIT

  • shared-memory

    fazerluga-creator
    A
    license
    Not graded
    quality
    C
    maintenance
    A portable, self-hosted semantic memory layer for LLM agents, enabling them to search and add memories by meaning over the Model Context Protocol.
    2
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/WazzaMo/vecfs'

If you have feedback or need assistance with the MCP directory API, please join our Discord server