Skip to main content
Glama
Sign In
mnemonic

mnemonic

by naveenadi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mnemonic

On-device hybrid search for markdown knowledge bases. BM25 + vector + LLM reranking with link graphs, time decay, and HyDE. Designed for pi coding agent.

Quick Start

Global mode (default)

All collections share one index at ~/.cache/mnemonic/index.sqlite. Search everything at once.

npm install -g @naveenadi/mnemonic
mne init
mne collection add ~/notes --name notes
mne index
mne embed
mne query "what was the Q4 planning discussion"

Project-local mode

Use --db for a per-repo index. Keeps project docs separate.

mne --db .mnemonic/index.sqlite init
mne --db .mnemonic/index.sqlite collection add . --name myproject
mne --db .mnemonic/index.sqlite index
mne --db .mnemonic/index.sqlite embed
mne --db .mnemonic/index.sqlite query "deploy steps"

Related MCP server: corpus-search-mcp

Features

  • Hybrid search — BM25 (FTS5) + Vector embeddings + RRF fusion

  • Structured queries — intent:, lex:, vec:, hyde: fields for deliberate retrieval

  • Query expansion — LLM generates alternative phrasings for better recall

  • HyDE — Hypothetical Document Embeddings

  • LLM reranking — Cross-encoder re-ranks top candidates with position-aware blending

  • Link graph — Wikilinks, backlinks, orphan detection, link boosting

  • Time decay — Exponential recency weighting (favor recent notes)

  • Tagging — Manual + frontmatter auto-parse

  • Context tree — Hierarchical metadata (mne:// virtual paths)

  • Smart chunking — Markdown heading-aware boundaries

  • Dual LLM backend — Ollama (default) or node-llama-cpp (self-contained GGUF models)

Pi Integration

Three layers plus an interactive setup command, each installable globally (all projects) or per project.

Layer

What

Global path

Per-project path

Interactive

/mne init walks through setup

—

—

MCP server

Typed tools: query, get, multi_get, status

~/.pi/agent/mcp.json

.pi/mcp.json

Pi skill

Bash commands via SKILL.md

~/.pi/agent/skills/mnemonic/

.pi/skills/mnemonic/

Pi extension

4 tools + /mne command via pi.registerTool/Command

~/.pi/agent/extensions/mnemonic/

.pi/extensions/mnemonic/

Interactive setup (extension required)

After installing the extension and running /reload, type:

/mne init

This walks through: scope (global vs project) → add directories → index → embed → configure MCP → install skill.

Other commands: /mne add <path>, /mne status, /mne help.

MCP — global

// ~/.pi/agent/mcp.json
{
  "mcpServers": {
    "mnemonic": {
      "command": "mne",
      "args": ["mcp"],
      "lifecycle": "keep-alive"
    }
  }
}

MCP — per project

Same config in .pi/mcp.json (project root).

Skill — global

mkdir -p ~/.pi/agent/skills/mnemonic
cp SKILL.md ~/.pi/agent/skills/mnemonic/

Skill — per project

mkdir -p .pi/skills/mnemonic
cp SKILL.md .pi/skills/mnemonic/

Extension — global

mkdir -p ~/.pi/agent/extensions/mnemonic
cp src/pi-extension/index.ts ~/.pi/agent/extensions/mnemonic/

Extension — per project

mkdir -p .pi/extensions/mnemonic
cp src/pi-extension/index.ts .pi/extensions/mnemonic/

Architecture

                    Core SDK (@naveenadi/mnemonic)
    Store (SQLite FTS5 + vec)  |  Search Pipeline  |  Chunker
                    LLM Backend (Ollama <-> node-llama-cpp)
                    Link Graph  |  Time Decay  |  HyDE
Query ──► HyDE ──► Query Expansion ──► BM25 + Vector (per variant)
                   │
                   └──► RRF Fusion ──► Reranking ──► Time Decay ──► Link Boost ──► Results

CLI Commands

mne init                     Initialize index
mne collection add <dir>     Add a collection
mne collection list          List collections
mne index                    Index all collections
mne embed                    Generate vector embeddings
mne search <query>           BM25 full-text search
mne vsearch <query>          Vector semantic search
mne query <query>            Hybrid search (BM25 + vector + reranking)
mne get <#docid|path>        Retrieve a document
mne multi-get <pattern>      Batch retrieve
mne ls [collection]          List files
mne status                   Show index status
mne doctor                   Diagnostic checks
mne context add <path> <txt> Add context metadata
mne tag <#docid> <tag>       Add a tag
mne links <#docid>           Show outgoing links
mne backlinks <#docid>       Show incoming links
mne orphans                  Find orphan documents
mne mcp                      Start MCP server

References

  • SKILL.md — Pi skill for agentic workflows (dig loop, cross-reference, setup)

  • references/setup.md — Detailed CLI setup and diagnostics

  • references/pi-integration.md — Pi integration: MCP, skill, extension (both modes)

  • references/link-graph.md — Cross-reference commands and usage

  • src/pi-extension/ — Pi extension source + standalone package.json

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • corpus-rag

      monahand1023
      A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for local RAG over personal notes, PDFs, and documents, enabling plain-English querying and hybrid search with multi-hop context expansion.
      MIT

    • ragmark

      cdcoonce
      A
      license
      Not graded
      quality
      B
      maintenance
      Local-first MCP server for retrieval over markdown wikilink vaults, offering hybrid vector+lexical search, note reading, neighbor expansion, and recent activity tracking with fully local embeddings and no network egress.
      MIT

    • metamind-vault-rag

      Nikitzu
      A
      license
      C
      quality
      D
      maintenance
      MCP server for hybrid retrieval over markdown vaults, combining sqlite-vec embeddings and FTS5 keywords with reciprocal rank fusion, plus optional cross-encoder reranking.
      3
      MIT