Provides AI agents with a local, deterministic BM25-indexed memory vault for persistent, offline-first text storage and retrieval.
Also known as ezumba/vanguard-memory-node, @lnes/vanguard-memory-node
- Stars
- 0
- Tools
- 13
- Downloads, 30 days
- 175
- Latest version
- 2.0.1
- Last commit
- Sep 5, 2026
- License
- MIT
What is Vanguard Memory Node MCP?
Vanguard Memory Node provides AI agents with a local, deterministic BM25-indexed memory vault for persistent, offline-first text storage and retrieval. It exposes 13 tools, such as text, title, namespace.
Summary generated from the project's README
About Vanguard Memory Node MCP server
Vanguard Memory Node provides AI agents with a local, deterministic memory vault for persistent text storage. Unlike cloud-based vector databases, this server operates entirely on your local disk, ensuring data privacy and offline availability. It uses a sharded BM25 inverted index to provide keyword-based retrieval that remains consistent regardless of model updates or semantic drift.
Developers can integrate this server into Claude Desktop or other MCP-compatible clients using npx. The system includes tools for ingesting text, searching the full vault, and managing files through a delta-ingestion process that tracks progress with cursors. For users requiring cross-device recall, the server supports syncing local objects to the ExergyNet LNES-17 ledger using an API key.
Technical features include SHA-256 content addressing, Unicode normalization, and a 13-rule suffix stemmer for improved search accuracy. The server manages its own local directory structure for authoritative object files, metadata catalogs, and index segments, making it a self-contained solution for agentic long-term memory.
What you can do with it
- 1Persistent local agent memoryStore and retrieve text data locally to ensure an AI agent has a consistent memory that does not rely on cloud services.
- 2Continuous log ingestionAutomatically ingest growing log files into the memory vault by tracking new lines with a cursor to avoid duplicates.
- 3Deterministic keyword searchPerform keyword searches across all stored objects to get ranked results that remain the same every time a query is run.
Written from the project's README. Every use case is checked against a quote from it.
How to install Vanguard Memory Node MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Vanguard Memory Node MCP in Claude Code
$ claude mcp add vanguard-memory-node -- npx -y @lnes/vanguard-memory-nodeInstall Vanguard Memory Node MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"vanguard-memory-node": {
"command": "npx",
"args": [
"-y",
"@lnes/vanguard-memory-node"
]
}
}
}Install Vanguard Memory Node MCP in VS Code
.vscode/mcp.json
{
"servers": {
"vanguard-memory-node": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@lnes/vanguard-memory-node"
]
}
}
}Install Vanguard Memory Node MCP in VS Code CLI
$ code --add-mcp '{"name":"vanguard-memory-node","type":"stdio","command":"npx","args":["-y","@lnes/vanguard-memory-node"]}'Install Vanguard Memory Node MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"vanguard-memory-node": {
"command": "npx",
"args": [
"-y",
"@lnes/vanguard-memory-node"
]
}
}
}Install Vanguard Memory Node MCP in Codex
$ codex mcp add vanguard-memory-node -- npx -y @lnes/vanguard-memory-nodeInstall Vanguard Memory Node MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.vanguard-memory-node] command = "npx" args = ["-y", "@lnes/vanguard-memory-node"]
Install Vanguard Memory Node MCP in Gemini CLI
$ gemini mcp add -s user vanguard-memory-node npx -- -y @lnes/vanguard-memory-nodeInstall Vanguard Memory Node MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"vanguard-memory-node": {
"command": "npx",
"args": [
"-y",
"@lnes/vanguard-memory-node"
]
}
}
}Vanguard Memory Node MCP tools 13
Detected from the READMEtexttitlenamespacetagscontent_typesourcehashquerylimitfile_pathsession_idxlmp_root
| text | — | |
| title | — | |
| namespace | — | |
| tags | — | |
| content_type | — | |
| source | — | |
| hash | — | |
| query | — | |
| limit | — | |
| file_path | — | |
| session_id | — | |
| xlmp_root | — |
Show all 13 toolsShow fewer tools
intent
| intent | — |
Configuration
AUTO_SYNC_VAULTEXERGYNET_API_KEYEXERGYNET_NETWORK
| Name | Description | |
|---|---|---|
| AUTO_SYNC_VAULT | — | |
| EXERGYNET_API_KEY | — | |
| EXERGYNET_NETWORK | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableezumba/vanguard-memory-node is public and reachablegithub.com/ezumba/vanguard-memory-node ↗Pass
- Package names this repository as its source@lnes/vanguard-memory-node names ezumba/vanguard-memory-node as sourcenpmjs.com/package/@lnes/vanguard-memory-node ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-05github.com/ezumba/vanguard-memory-node ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @lnes/vanguard-memory-nodePass
- No critical advisory in the package or its dependencies100 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model13 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubVanguard 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.
| 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 -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.
| 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 (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
- Normalization — Unicode NFC → phrase alias substitution → tokenize → suffix stem → stop-word filter → token alias expansion
- 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;medicationsandmedicationboth reduce to the same root. - Alias expansion — clinical, technical, and legal synonym clusters (
smok↔tobacco↔cigarett,physician↔doctor,hypertens↔bp, etc.) - BM25 scoring — sharded 256-bucket inverted index; top-150 postings per term to cap high-DF stall
- 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.
Vanguard Memory Node MCP questions
How do I add Vanguard Memory Node MCP to Claude Code?
Run claude mcp add vanguard-memory-node -- npx -y @lnes/vanguard-memory-node in your terminal. Add --scope user to make it available in every project.
How do I add Vanguard Memory Node MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Vanguard Memory Node MCP provide?
It exposes 13 tools, including text, title, namespace, tags, content_type.
Does this require a cloud connection or API key?
No, it is an offline-first solution that stores data entirely on your local disk. An API key is only required if you choose to sync vaults to the ExergyNet ledger.
How does the retrieval process work?
It uses a deterministic BM25 scoring system with a sharded inverted index, involving normalization, suffix stemming, and alias expansion.
Can I ingest files continuously without creating duplicates?
Yes, the vmn_ingest_file tool tracks progress with a cursor, allowing it to only ingest new lines from growing files.