MCP Server for reduce use of Token

Nxm-memory, a local memory and search engine for AI assistants, indexes an entire workspace on the user's own machine and exposes its tools through the Model Context Protocol (MCP) to cut the number of tokens sent to a model. The tool compresses source code into structural maps plus shell output and chat history, and for prose documents retrieves only relevant chunks via search instead of loading whole files, with a dedicated semantic document-compression mode listed on the roadmap. It installs via a single curl command to ~/.local/bin, supports macOS arm64 (Apple Silicon) and Linux x86_64, and downloads a roughly 200 MB embedding model plus the ONNX Runtime library on first run.

nxm-memory is a local memory and search engine for AI assistants. Although it works great for coding projects, it is not limited to code — it can index and search any collection of files: documentation, notes, research, contracts, knowledge bases, and more. It indexes an entire workspace on your own machine and makes it queryable in natural language, without sending anything to the cloud. It reads the documents in your workspace and gives you fast, relevant answers about them. It also cuts the number of tokens sent to the model: it compresses source code into structural maps, plus shell output and chat history, and — crucially for documents — it retrieves only the relevant chunks via search instead of loading whole files. It exposes its tools through the Model Context Protocol MCP , so it plugs into agents like Claude Code, Opencode, Pi, and others. Important ⭐ Token reduction to cut cost and fit more in context — one of the most important features. nxm-memory compresses source code into structural maps , shell output, and chat history before they reach the model. For prose documents Markdown, text, PDF , it saves tokens by searching and returning only the relevant chunks rather than compressing whole files. A dedicated semantic document-compression mode is on the roadmap. It is configured exactly like any other MCP server. Everything runs locally: fast, private, always available. See nxm-memory in action: One command. It auto-detects your system macOS Apple Silicon or Linux x86 64 , downloads the binary, and installs it to ~/.local/bin : curl -fsSL https://raw.githubusercontent.com/dangranaz/nxm-memory/main/install.sh | sh On first run , the program automatically downloads the embedding model ~200 MB and the required ONNX Runtime library. There is nothing else to download by hand. If ~/.local/bin is not on your PATH , add it: export PATH="$HOME/.local/bin:$PATH" Supported platforms: macOS arm64 Apple Silicon and Linux x86 64 . nxm-memory is a standard MCP server, so you can configure it in your agents, your harnesses, and any tool that supports the MCP standard. Here is an example for OpenCode — add it to your opencode.json global or opencode.jsonc under the mcp key. Point --w at the project you want indexed: { "$schema": "https://opencode.ai/config.json", "mcp": { "nxm-memory": { "type": "local", "command": "nxm-mcp-server", "--w", "/path/to/your/project", "--transport", "stdio" , "enabled": true } } } The configuration follows the same pattern in other agents Claude Code, Pi, Cursor, Kiro… : a local MCP server whose command is nxm-mcp-server with --transport stdio . Start the server pointing it at your project folder the workspace . On startup it scans the folder and builds its index: nxm-mcp-server --w /path/to/your/project --port 7169 The server stays running and keeps the index up to date automatically as files change. To stop it: nxm-mcp-server --stop Create a .nxmignore file at the root of your project to tell nxm-memory which folders and files not to index. The syntax is the same as .gitignore . This matters: without exclusions, huge and useless folders dependencies, build output, artifacts would end up in the index, slowing everything down and polluting search results. Recommended .nxmignore example: Dependencies and packages node modules/ vendor/ .venv/ venv/ Build output and artifacts target/ dist/ build/ out/ .min.js .min.css Version control and caches .git/ .cache/ pycache / Lock files and logs .lock .log Useful rules: - one pattern per line; starts a comment; - a trailing / e.g. build/ matches directories only; - pattern re-includes something excluded earlier; - the data folder .nxm/ is always excluded automatically the index never ingests its own state . To use it inside an agent Claude Code, Cursor, Kiro… , use the stdio transport, with the agent managing the process lifecycle: nxm-mcp-server --w /path/to/your/project --transport stdio Think of nxm-memory as long-term memory for your AI assistant , dedicated to a project. When you give it a folder, it reads everything and breaks it into small pieces "chunks" . For each piece it stores two things: the exact words it contains and its meaning . Meaning is captured with an embedding model a neural network that turns text into numbers, so that texts meaning similar things end up "close" together . This way you can search either for a precise word or for a concept expressed with words different from those in the code. Search combines three approaches — exact match, keyword search, and meaning-based search — and blends their results to surface the most relevant answers at the top. Memory is organized into four types , much like human memory: - Semantic — stable facts, rules, and preferences e.g. "this project uses Rust", "I prefer tests before code" . - Episodic — events and sessions: what happened and when. - Procedural — skills and procedures: how a given thing is done in this project. - Prospective — tasks to do and future reminders. It has been tested on workspaces of tens of gigabytes mixing documents and code hundreds of thousands of files . And it does not stop after the first scan: it stays running in the background , constantly keeping the vector database up to date — every file you add to or change in the workspace is picked up and re-indexed automatically. Everything lives on your computer, in a .nxm/ folder inside the project. Nothing leaves your machine. nxm-memory gives an AI assistant persistent memory and instant search over a project: it retrieves the right function, the relevant document, or the decision made weeks ago, without having to re-read everything each time. It builds and maintains the index of the project and answers the agent's queries. Important Token reduction — one of the most valuable features. nxm-memory includes a built-in context-compression engine context compress that shrinks source code into structural maps , shell output, and chat history before they reach the model. It reports how many tokens it saved tokens before / tokens after / reduction pct , keeping long agent sessions inside the context window and cutting cost — while preserving errors and the important parts. For prose documents Markdown/text/PDF it does not yet compress semantically; use search docs / index search to load only the relevant chunks. A semantic document-compression mode is planned see roadmap . Example — compressing a real source file into its structural map: context compress mode: file tokens before: 3050 tokens after : 416 reduction : 87% saved That is 2634 tokens saved on a single file — multiplied across every file, shell output, and chat turn an agent handles in a session. On startup and whenever files change it builds the index of the workspace. Indexing is incremental: only files that actually changed are reprocessed. - Code : Rust, Python, JavaScript/TypeScript .rs , .py , .js , .jsx , .ts , .tsx , plus .sh , .sql , .proto , .graphql , .html , .css . - Documents : Markdown .md , .mdx , PDF, plain text .txt , .rst , .adoc . - Configuration : .toml , .yaml / .yml , .json , .ini , .cfg . Folders listed in .nxmignore are skipped see section 2 . The server exposes these tools to the AI agent: | Tool | What it does | |---|---| | index workspace | Index or re-index a workspace automatic full/incremental . | | index search | Hybrid search meaning + keywords + fusion across everything indexed. | | search code | Search code files only, with language and path filters. | | search docs | Search documents only PDF, Markdown, TXT . | | search exact | Exact substring search, very fast, no embedding needed. | | search regex | Search with regular expressions. | | get chunk | Retrieve the full content of a chunk by ID on-demand loading . | | find symbol | Find the definition of a symbol function, struct, class… . | | outline | List the top-level symbols of a file. | | find references | Find all uses of a symbol across a project. | | memory remember | Store a fact, event, skill, or task in memory. | | memory recall | Search memory for relevant facts, events, and skills. | | context compress | Reduce token usage : compress source code into structural maps , shell output, or chat history — reports tokens saved. For prose documents, prefer search docs / index search . One of the most useful tools. | | context budget | Compute the optimal context allocation for a given window. | | workspace list / workspace create | List / create configured workspaces. | | stats | Index statistics files indexed, chunks, storage . | | watcher status | Status of the automatic file watcher. | If nxm-memory saves you tokens, time, or keeps your data private, please give the repository a star and share it — it is the simplest way to help the project grow and reach other developers. Feedback and suggestions are welcome via issues. The source code is maintained privately. This repository distributes the binaries and the installer; the embedding model is distributed separately and downloaded automatically on first run.