io.github.ezumba/vanguard-memory-node

Vanguard Memory Node (VMN)

Local deterministic memory for AI agents via the Model Context Protocol (MCP).

No cloud. No vector database. No semantic drift. Your data stays on your machine.

What it does

VMN gives any MCP-compatible AI agent a persistent, queryable memory vault stored entirely on local disk. Text is ingested once, content-addressed with SHA-256, segmented, and indexed with a sharded BM25 inverted index. Retrieval is deterministic: the same query always returns the same ranked result from the same data.

Optionally, vaults can be synced to the ExergyNet LNES-17 ledger for cross-device and cross-agent recall with cryptographic provenance.

Install

npm install -g @lnes/vanguard-memory-node

Or run without installing:

npx @lnes/vanguard-memory-node

Claude Desktop integration

Mac — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "npx",
      "args": ["-y", "@lnes/vanguard-memory-node"]
    }
  }
}

With ExergyNet vault sync enabled:

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "npx",
      "args": ["-y", "@lnes/vanguard-memory-node"],
      "env": {
        "EXERGYNET_API_KEY": "sk-exergy-your-key",
        "EXERGYNET_NETWORK": "mainnet",
        "AUTO_SYNC_VAULT": "true"
      }
    }
  }
}

WSL on Windows:

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "npx", "-y", "@lnes/vanguard-memory-node"]
    }
  }
}

Tools (11 total)

vmn_ingest

Stores text as a SHA-256 content-addressed shard. Segments it, indexes it, and updates the local catalog.

Returns: SHA-256 root hash + vault path + vault_synced flag.

vmn_recall

Retrieves a 900-character evidence window from a specific shard using lexical BM25 scoring.

Returns: best-matching evidence window, or a human-readable no-match message.

vmn_search

Full-vault keyword search across all ingested objects. Returns ranked results with snippets.

vmn_ingest_file

Delta-ingests a growing file into the vault, tracking progress with a cursor so only new lines are ingested on each call. Designed for Stop hooks and continuous log pipelines — safe to call repeatedly with no duplicates.

Returns: lines_ingested, cursor_line, and shard hash (null if no new content).

Stop hook example — ingest every Claude session automatically:

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "npx -y @lnes/vanguard-memory-node vmn_ingest_file --file_path \"$CLAUDE_SESSION_FILE\" --session_id \"$CLAUDE_SESSION_ID\""
      }]
    }]
  }
}

vmn_list

Lists all memory objects in the vault.

vmn_inspect

Returns full catalog metadata for a specific object.

vmn_delete

Permanently removes an object and all its index entries.

vmn_stats

Returns aggregate vault statistics: entry count, total bytes, namespaces, oldest/newest timestamps.

vmn_index_status

Returns current BM25 index state (READY, REBUILD_REQUIRED, REBUILDING, DEGRADED).

vmn_rebuild_index

Rebuilds the full BM25 index from authoritative object files. Safe at any time — objects are never modified.

vmn_sync_vault

Syncs a local memory object to the ExergyNet LNES-17 vault. Requires EXERGYNET_API_KEY. Use EXERGYNET_NETWORK to target mainnet or testnet.

Returns: xlmp_root, bytes_committed, status, and the resolved vault URL.

Environment variables

Vault layout

~/.vanguard/
├── local_vault/
│   └── <sha256>.txt              # authoritative object files (never modified after write)
├── catalog/
│   └── <sha256>.json             # per-object metadata (O(1) reads)
├── segments/
│   └── <sha256>.json             # segment records with term frequencies
├── cursors/
│   └── <session_id>.json         # cursor state for vmn_ingest_file
└── index/
    └── v2/
        ├── index_manifest.json   # version + state header
        ├── corpus_stats.json     # BM25 corpus statistics
        └── postings/
            └── <2-hex>.json      # 256 sharded posting buckets

How retrieval works

1. Normalization — Unicode NFC → phrase alias substitution → tokenize → suffix stem → stop-word filter → token alias expansion
2. Stemmer — 13-rule suffix stripper: tions→ (5), ions→ (4), tion→ (4), ings→ (4), ing→ (3), ers→ (3), ies→ (3), ic→ (2), er→ (2), ed→ (2), es→ (2), s→ (1), y→ (1). Rules applied longest-first; medications and medication both reduce to the same root.
3. Alias expansion — clinical, technical, and legal synonym clusters (smok↔tobacco↔cigarett, physician↔doctor, hypertens↔bp, etc.)
4. BM25 scoring — sharded 256-bucket inverted index; top-150 postings per term to cap high-DF stall
5. Fallback — stemmed-token set comparison when BM25 score is zero; prevents false positives on partial-word matches

Comparison

License

MIT — free forever, no telemetry, no usage limits.

Built by ExergyNet.