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"

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