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 vanguard-memory-node

Or run without installing:

npx 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", "vanguard-memory-node"]
    }
  }
}

With ExergyNet vault sync enabled:

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "npx",
      "args": ["-y", "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", "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 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.