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.

| Parameter | Type | Required | Description | |---|---|---|---| | text | string | yes | Content to store | | title | string | no | Human-readable label | | namespace | string | no | Logical partition (default: default) | | tags | string[] | no | Search tags | | content_type | string | no | MIME type hint (default: text/plain) | | source | string | no | Source label |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | hash | string | yes | Root hash from vmn_ingest | | query | string | yes | Search query |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | query | string | yes | Search query | | limit | number | no | Max results (default: 10) | | namespace | string | no | Restrict search to this namespace only |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | file_path | string | yes | Absolute path to the file | | session_id | string | no | Cursor key (defaults to file path) | | namespace | string | no | Namespace for ingested content (default: file_ingest) | | title | string | no | Optional title override | | tags | string[] | no | Optional tags |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | namespace | string | no | Filter by namespace |

vmn_inspect

Returns full catalog metadata for a specific object.

| Parameter | Type | Required | Description | |---|---|---|---| | hash | string | yes | Root hash |

vmn_delete

Permanently removes an object and all its index entries.

| Parameter | Type | Required | Description | |---|---|---|---| | hash | string | yes | Root hash |

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.

| Parameter | Type | Required | Description | |---|---|---|---| | xlmp_root | string | yes | Root hash of the object to sync | | intent | string | no | Sync intent label (default: manual-sync) |

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

Environment variables

| Variable | Default | Description | |---|---|---| | AUTO_SYNC_VAULT | false | Set to true to auto-sync every vmn_ingest to ExergyNet | | EXERGYNET_API_KEY | — | API key for ExergyNet vault access (sk-exergy-*) | | EXERGYNET_NETWORK | testnet | Target substrate: mainnet → portal.exergynet.org, testnet → dt.portal.exergynet.org | | EXERGYNET_VAULT_URL | (resolved from EXERGYNET_NETWORK) | Override vault base URL entirely |

Vault layout

~/.vanguard/
├── local_vault/
│   └── <sha256>.txt              # authoritative object files (never modified after write)
├── catalog/
│   └── <sha256>.json             # per-object metadata (direct hash-keyed 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

| | VMN | ChromaDB / Pinecone | |---|---|---| | Result determinism | Same query → same result, always | Varies with model version | | Data location | Local disk only | Cloud upload required | | Per-query cost | $0 | API charges | | Setup time | 60 seconds | Account + key + SDK | | Semantic drift | None | Breaks on model updates | | Offline capable | Yes | No |

License

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

Built by ExergyNet.