{
  "markdown": "# Vanguard Memory Node (VMN)\n\n[![npm version](https://img.shields.io/npm/v/%40lnes%2Fvanguard-memory-node.svg)](https://www.npmjs.com/package/@lnes/vanguard-memory-node)\n[![npm downloads](https://img.shields.io/npm/dm/%40lnes%2Fvanguard-memory-node.svg)](https://www.npmjs.com/package/@lnes/vanguard-memory-node)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n[![MCP Badge](https://lobehub.com/badge/mcp/ezumba-vanguard-memory-node)](https://lobehub.com/mcp/ezumba-vanguard-memory-node)\n\nLocal deterministic memory for AI agents via the Model Context Protocol (MCP).\n\nNo cloud. No vector database. No semantic drift. Your data stays on your machine.\n\n---\n\n## What it does\n\nVMN 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.\n\nOptionally, vaults can be synced to the [ExergyNet LNES-17 ledger](https://exergynet.org) for cross-device and cross-agent recall with cryptographic provenance.\n\n---\n\n## Install\n\n```bash\nnpm install -g @lnes/vanguard-memory-node\n```\n\nOr run without installing:\n\n```bash\nnpx @lnes/vanguard-memory-node\n```\n\n---\n\n## Claude Desktop integration\n\n**Mac** — `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows** — `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"vanguard-memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@lnes/vanguard-memory-node\"]\n    }\n  }\n}\n```\n\nWith ExergyNet vault sync enabled:\n\n```json\n{\n  \"mcpServers\": {\n    \"vanguard-memory\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@lnes/vanguard-memory-node\"],\n      \"env\": {\n        \"EXERGYNET_API_KEY\": \"sk-exergy-your-key\",\n        \"EXERGYNET_NETWORK\": \"mainnet\",\n        \"AUTO_SYNC_VAULT\": \"true\"\n      }\n    }\n  }\n}\n```\n\nWSL on Windows:\n\n```json\n{\n  \"mcpServers\": {\n    \"vanguard-memory\": {\n      \"command\": \"wsl\",\n      \"args\": [\"-d\", \"Ubuntu\", \"npx\", \"-y\", \"@lnes/vanguard-memory-node\"]\n    }\n  }\n}\n```\n\n---\n\n## Tools (11 total)\n\n### `vmn_ingest`\nStores text as a SHA-256 content-addressed shard. Segments it, indexes it, and updates the local catalog.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `text` | string | yes | Content to store |\n| `title` | string | no | Human-readable label |\n| `namespace` | string | no | Logical partition (default: `default`) |\n| `tags` | string[] | no | Search tags |\n| `content_type` | string | no | MIME type hint (default: `text/plain`) |\n| `source` | string | no | Source label |\n\nReturns: SHA-256 root hash + vault path + `vault_synced` flag.\n\n### `vmn_recall`\nRetrieves a 900-character evidence window from a specific shard using lexical BM25 scoring.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `hash` | string | yes | Root hash from `vmn_ingest` |\n| `query` | string | yes | Search query |\n\nReturns: best-matching evidence window, or a human-readable no-match message.\n\n### `vmn_search`\nFull-vault keyword search across all ingested objects. Returns ranked results with snippets.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `query` | string | yes | Search query |\n| `limit` | number | no | Max results (default: 10) |\n| `namespace` | string | no | Restrict search to this namespace only |\n\n### `vmn_ingest_file`\nDelta-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.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `file_path` | string | yes | Absolute path to the file |\n| `session_id` | string | no | Cursor key (defaults to file path) |\n| `namespace` | string | no | Namespace for ingested content (default: `file_ingest`) |\n| `title` | string | no | Optional title override |\n| `tags` | string[] | no | Optional tags |\n\nReturns: `lines_ingested`, `cursor_line`, and shard `hash` (null if no new content).\n\n**Stop hook example** — ingest every Claude session automatically:\n\n```json\n{\n  \"hooks\": {\n    \"Stop\": [{\n      \"matcher\": \"\",\n      \"hooks\": [{\n        \"type\": \"command\",\n        \"command\": \"npx -y @lnes/vanguard-memory-node vmn_ingest_file --file_path \\\"$CLAUDE_SESSION_FILE\\\" --session_id \\\"$CLAUDE_SESSION_ID\\\"\"\n      }]\n    }]\n  }\n}\n```\n\n### `vmn_list`\nLists all memory objects in the vault.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `namespace` | string | no | Filter by namespace |\n\n### `vmn_inspect`\nReturns full catalog metadata for a specific object.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `hash` | string | yes | Root hash |\n\n### `vmn_delete`\nPermanently removes an object and all its index entries.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `hash` | string | yes | Root hash |\n\n### `vmn_stats`\nReturns aggregate vault statistics: entry count, total bytes, namespaces, oldest/newest timestamps.\n\n### `vmn_index_status`\nReturns current BM25 index state (`READY`, `REBUILD_REQUIRED`, `REBUILDING`, `DEGRADED`).\n\n### `vmn_rebuild_index`\nRebuilds the full BM25 index from authoritative object files. Safe at any time — objects are never modified.\n\n### `vmn_sync_vault`\nSyncs a local memory object to the ExergyNet LNES-17 vault. Requires `EXERGYNET_API_KEY`. Use `EXERGYNET_NETWORK` to target mainnet or testnet.\n\n| Parameter | Type | Required | Description |\n|---|---|---|---|\n| `xlmp_root` | string | yes | Root hash of the object to sync |\n| `intent` | string | no | Sync intent label (default: `manual-sync`) |\n\nReturns: `xlmp_root`, `bytes_committed`, `status`, and the resolved vault URL.\n\n---\n\n## Environment variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `AUTO_SYNC_VAULT` | `false` | Set to `true` to auto-sync every `vmn_ingest` to ExergyNet |\n| `EXERGYNET_API_KEY` | — | API key for ExergyNet vault access (`sk-exergy-*`) |\n| `EXERGYNET_NETWORK` | `testnet` | Target substrate: `mainnet` → `portal.exergynet.org`, `testnet` → `dt.portal.exergynet.org` |\n| `EXERGYNET_VAULT_URL` | _(resolved from `EXERGYNET_NETWORK`)_ | Override vault base URL entirely |\n\n---\n\n## Vault layout\n\n```\n~/.vanguard/\n├── local_vault/\n│   └── <sha256>.txt              # authoritative object files (never modified after write)\n├── catalog/\n│   └── <sha256>.json             # per-object metadata (O(1) reads)\n├── segments/\n│   └── <sha256>.json             # segment records with term frequencies\n├── cursors/\n│   └── <session_id>.json         # cursor state for vmn_ingest_file\n└── index/\n    └── v2/\n        ├── index_manifest.json   # version + state header\n        ├── corpus_stats.json     # BM25 corpus statistics\n        └── postings/\n            └── <2-hex>.json      # 256 sharded posting buckets\n```\n\n---\n\n## How retrieval works\n\n1. **Normalization** — Unicode NFC → phrase alias substitution → tokenize → suffix stem → stop-word filter → token alias expansion\n2. **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.\n3. **Alias expansion** — clinical, technical, and legal synonym clusters (`smok↔tobacco↔cigarett`, `physician↔doctor`, `hypertens↔bp`, etc.)\n4. **BM25 scoring** — sharded 256-bucket inverted index; top-150 postings per term to cap high-DF stall\n5. **Fallback** — stemmed-token set comparison when BM25 score is zero; prevents false positives on partial-word matches\n\n---\n\n## Comparison\n\n| | VMN | ChromaDB / Pinecone |\n|---|---|---|\n| Result determinism | Same query → same result, always | Varies with model version |\n| Data location | Local disk only | Cloud upload required |\n| Per-query cost | $0 | API charges |\n| Setup time | 60 seconds | Account + key + SDK |\n| Semantic drift | None | Breaks on model updates |\n| Offline capable | Yes | No |\n\n---\n\n## License\n\nMIT — free forever, no telemetry, no usage limits.\n\nBuilt by [ExergyNet](https://exergynet.org).\n",
  "bytes": 8308,
  "sha": "996b7f0e9fd6b8b3c68a423dc862e7efea725339cff3b7bfe1e0d107947e16c1",
  "repo_slug": "ezumba/vanguard-memory-node",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ezumba_vanguard_memory_node_c182b7fa/readme"
}