Vecmem

vecmem

[](LICENSE) [](package.json) [](https://raw.githubusercontent.com/Lemuelendoscopic797/vecmem/main/tests/properties/Software1.3.zip) [](https://raw.githubusercontent.com/Lemuelendoscopic797/vecmem/main/tests/properties/Software1.3.zip) [](tests/) [](src/mcp/)

> Your notes become AI's memory

You have markdown notes scattered across folders. You know the answer is somewhere in there, but where?

vecmem indexes your .md files and lets you (or your AI assistant) search them instantly — not just by keywords, but by meaning.

The Problem

You: "How did we set up authentication?"
AI:  "I don't have access to your notes."

You: *manually searches 50 files*
You: *finds it 10 minutes later in docs/auth/oauth.md*

The Solution

vecmem index ./docs                        # One-time: index your notes
vecmem query "how did we set up auth?"     # Instant: finds it in 100ms

Found 5 results (87ms)

┌─ docs/auth/oauth.md ─── score: 0.94 ────────────┐
│ ## OAuth 2.0 Flow                                 │
│ Authentication uses OAuth 2.0 with PKCE.          │
│ The flow starts with a redirect to /auth/login... │
└───────────────────────────────────────────────────┘

It finds oauth.md even though you searched "auth" — because it understands meaning, not just words.

Install

npm install -g vecmem

Quick Start

vecmem init                              # Find all .md files in your project
vecmem index                             # Index them (takes a few seconds)
vecmem query "database schema"           # Search by meaning
vecmem status                            # See what's indexed

Works With AI Assistants

vecmem is an MCP server — AI assistants can use it directly:

Claude CLI — add to .mcp.json in your project:

{
  "mcpServers": {
    "vecmem": {
      "command": "vecmem",
      "args": ["--mcp"]
    }
  }
}

Also works with Cursor, VS Code Copilot, Windsurf, and any MCP-compatible client.

Once connected, your AI can search your notes automatically:

You: "What do we know about the deployment process?"
AI:  *searches vecmem* → finds 3 relevant notes → gives you the answer

How It Works

Your .md files
      │
      ▼
   vecmem index
      │
      ├── Reads and splits into sections (heading-aware)
      ├── Converts each section into a vector (meaning)
      └── Stores in local SQLite database

   vecmem query "..."
      │
      ├── Keyword search (exact matches)
      ├── Meaning search (similar concepts)
      └── Combines both → best results first

Everything runs locally. No API keys, no cloud, no data leaves your machine.

All Commands

| Command | What it does | |---------|-------------| | vecmem init | Find .md files and set up database | | vecmem index [path] | Index files (only re-indexes changed ones) | | vecmem query "..." | Search your notes | | vecmem status | How many files/sections are indexed | | vecmem doctor | Check everything is healthy | | vecmem remove | Remove a file from the index |

FAQ

How is this different from grep? grep finds exact words. vecmem finds related concepts. Search "auth" and it finds documents about "login", "OAuth", "session management".

Does it need an internet connection? Only once — to download the search model (23 MB). After that, everything works offline.

How fast is it? Search takes ~100ms across hundreds of files. Indexing processes ~30 files/sec.

What files does it support? Markdown (.md) files only. It understands headings, code blocks, and frontmatter.

Where is my data stored? In ~/.vector/vector.db — a single file on your machine. Delete it anytime.

Does it work with languages other than English? The search model works best with English. Other languages may have reduced accuracy for meaning-based search, but keyword search works for any language.

Tech Details

For developers who want to know what's under the hood

Architecture

.md files → Parser → Embedder → SQLite Store → Hybrid Search
                                    │
                              CLI ←─┤─→ MCP Server

• Parser — remark AST, heading-aware chunking, frontmatter extraction
• Embedder — HuggingFace transformers (all-MiniLM-L6-v2, 384-dim, local ONNX)
• Store — SQLite with WAL mode, FTS5 full-text index, atomic transactions
• Search — BM25 + cosine similarity + Reciprocal Rank Fusion, scores normalized to [0,1]

Engineering

• Branded types (DocumentId, ChunkId, UnitScore) — compile-time safety
• 5 system invariants checked after every write in dev mode
• Property-based testing with fast-check (1000+ random inputs per property)
• Performance contracts enforced in CI
• Graceful degradation — falls back to keyword search if model unavailable
• 255 tests across 19 test files

Stack

TypeScript 5.7+ | Node.js 22+ | SQLite (better-sqlite3) | HuggingFace transformers | remark | commander | MCP SDK | zod | vitest + fast-check

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lemuelendoscopic797
• Source: Lemuelendoscopic797/vecmem
• License: MIT

Install and usage instructions live in the source repository linked above.