Contextful MCP server
✓ VerifiedProvides a local search engine and memory layer for coding agents to efficiently retrieve, compress, and remember project context.
Also known as Inferensys/contextful, @inferensys/contextful
- Stars
- 6
- Tools
- 7
- Downloads, 30 days
- 182
- Latest version
- 0.1.0
- Last commit
- May 23, 2026
- License
- MIT
What is Contextful MCP?
Contextful provides a local search engine and memory layer for coding agents to efficiently retrieve, compress, and remember project context. It exposes 7 tools, such as context_pack, search_code, trace_path.
Summary generated from the project's README
About Contextful MCP server
Contextful provides a local search engine and memory layer designed specifically for agentic AI coding tools. It functions as a runtime contextual layer that helps agents find, compress, and remember project information without reading dozens of files every session. By indexing a project once, it generates ranked and cited context packs that respect specific token budgets, making it more efficient than standard file reading methods.
Developers can use this as an MCP server, a local daemon, or via a CLI tool named cxf. It integrates with various coding environments including Cursor, Windsurf, Claude Code, VS Code, and Zed. The system uses a local SQLite store with FTS5 lexical search and typed graph tables to manage relationships between files and symbols. Because it is local-only, it does not upload source code or call external embedding APIs, ensuring project privacy.
Key tools available to agents include context_pack for retrieving budgeted bundles, search_code for finding documentation or symbols, and write_lesson for storing evidence-backed memories in a durable ledger.
What you can do with it
- 1Store durable project learningsInstruct the agent to save a specific architectural decision or lesson to be remembered in future sessions.
- 2Analyze code dependenciesRequest a trace of how different modules or symbols relate to one another through the project graph.
- 3Perform impact analysisAsk the agent to determine which parts of the system might be affected by changing a specific symbol.
Written from the project's README. Every use case is checked against a quote from it.
How to install Contextful MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Contextful MCP in Claude Code
$ claude mcp add contextful -- npx -y @inferensys/contextfulInstall Contextful MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"contextful": {
"command": "npx",
"args": [
"-y",
"@inferensys/contextful"
]
}
}
}Install Contextful MCP in VS Code
.vscode/mcp.json
{
"servers": {
"contextful": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@inferensys/contextful"
]
}
}
}Install Contextful MCP in VS Code CLI
$ code --add-mcp '{"name":"contextful","type":"stdio","command":"npx","args":["-y","@inferensys/contextful"]}'Install Contextful MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"contextful": {
"command": "npx",
"args": [
"-y",
"@inferensys/contextful"
]
}
}
}Install Contextful MCP in Codex
$ codex mcp add contextful -- npx -y @inferensys/contextfulInstall Contextful MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.contextful] command = "npx" args = ["-y", "@inferensys/contextful"]
Install Contextful MCP in Gemini CLI
$ gemini mcp add -s user contextful npx -- -y @inferensys/contextfulInstall Contextful MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"contextful": {
"command": "npx",
"args": [
"-y",
"@inferensys/contextful"
]
}
}
}Contextful MCP tools 7
Detected from the READMEcontext_packsearch_codetrace_pathimpact_analysiswhy_changedrecall_memorywrite_lesson
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 reachableinferensys/contextful is public and reachablegithub.com/inferensys/contextful ↗Pass
- Package names this repository as its source@inferensys/contextful names inferensys/contextful as sourcenpmjs.com/package/@inferensys/contextful ↗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-05-23github.com/inferensys/contextful ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @inferensys/contextfulPass
- No critical advisory in the package or its dependencies156 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model7 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 GitHubContextful
⚠️ This is in early alpha. The API, features, and integrations are not stable. Expect breaking changes. Feedback & contributions are very welcome!
Local Context Management + Search Engine + Memory for Agentic AI.
Contextful is a runtime contextual layer and local search engine for agents that gives them one fast way to find, compress, cite, and remember project context.
Available as a CLI-first tool with an MCP runtime bridge and generated agent instructions, it integrates seamlessly with Codex, Claude Code, Cursor, Windsurf, GitHub Copilot, VS Code, Cline, Roo Code, Continue, and Zed.
Instead of making an agent read 40 files every session, Contextful indexes the project once and returns a ranked, cited, token-budgeted context pack.
Why?
Context has always been a bottleneck for agentic AI. Large context window models (for example, 1M tokens) are:
- Expensive and require significantly more compute & processing time.
- More likely to lose key information as the context window fills up.
- Most projects have millions of lines of code, but agents can only fit in limited tokens per context window.
The current solution is to make the agent guess which files to read, then pay the token cost to read them every session. This is slow, expensive, and lossy.
Apart from this, agents have no way to store or share learnings across sessions. Every time they start, they forget everything and have to re-read the same context again.
I started developing Contextful to keep the context window smaller by enabling efficient knowledge retrieval. If we index the project and return a ranked, cited, token-budgeted context pack, we can:
- 100x more efficient token usage: stop paying tokens to re-read the same files.
- Fewer tool calls: one context pack can replace dozens of grep, glob, and read-file calls.
- No lost context between sessions: agents can store session learnings in an evidence-backed memory ledger.
- Shareable project knowledge: lessons and context packs survive context compaction and future sessions.
Key Features
1. Context Management
The default local store is SQLite with FTS-backed search and typed graph tables. V1 ships with:
- SQLite as the default local store.
- FTS5 lexical/BM25 search.
- Typed graph tables:
nodes,edges,node_props,edge_props. - A hot adjacency cache for common graph relations.
- Deterministic structural fingerprints inspired by Code2Vec-style secondary reranking signals.
The next storage upgrades are optional semantic vectors through sqlite-vec, LanceDB, or local HNSW, and compressed adjacency lists with Roaring bitmaps or CSR arrays for larger repositories.
2. Search Engine
Contextful analyzes the query, classifies intent, and combines lexical search, symbols, docs, graph relationships, and memory hits to retrieve the right evidence. The goal is Google-level project search for agents: vague queries like "resources for auth onboarding" should still land on the right code, docs, and prior lessons.
3. Memory Ledger
Agents can store lessons, decisions, and useful project facts, but not as loose "remember this" notes. Every memory requires evidence refs from files, symbols, commits, or prior context packs. When the evidence changes, Contextful marks the memory stale.
4. Contextful Execution
Contextful is an MCP server, local indexer, and small CLI:
- MCP server: the agent interface.
- Local daemon / watcher: indexing, rebuilds, freshness, and future benchmarks.
- CLI (
cxf): human setup, indexing, search, memory writes, and local smoke tests.
MCP is the right interface because tools, resources, and prompts are exactly what MCP standardizes. The agent asks for context; Contextful returns compact evidence.
Install
npx @inferensys/contextful init --workspace .
npx @inferensys/contextful search "where is user auth handled" --workspace . --budget 2000
Run as an MCP server:
npx @inferensys/contextful server
CLI
The primary binary is cxf; contextful is also provided as a readable alias.
cxf init --workspace <path>
cxf index --workspace <path> [--watch]
cxf daemon --workspace <path>
cxf search "<query>" --workspace <path> --budget 2000 --json
cxf memory add --workspace <path> --claim <text> --evidence <ref>
cxf server
Core MCP Tools
Keep the agent surface small:
context_pack(query, budget, scope)- the killer tool. Returns a ranked, cited, token-budgeted bundle instead of forcing 40 random file reads.search_code(query, mode, filters)- powerful code, docs, symbol, and memory search.trace_path(from, to, edge_types)- graph traversal across files, symbols, modules, and config.impact_analysis(symbol_or_file)- reverse dependencies and likely tests.why_changed(symbol_or_file)- current evidence plus git history.recall_memory(query, scope)- search session learnings and durable project lessons.write_lesson(claim, evidence_refs, scope)- store an evidence-backed memory.
MCP Client Setup
Use this stdio server command in any MCP-aware coding tool:
{
"mcpServers": {
"contextful": {
"command": "npx",
"args": ["-y", "@inferensys/contextful", "server"]
}
}
}
Codex:
codex mcp add contextful -- npx -y @inferensys/contextful server
CLI-First Agent Flow
Use cxf init once per workspace. It indexes the project and writes .contextful/AGENT_INSTRUCTIONS.md, a compact skill-style guide that tells agents when to call context_pack, when to search more narrowly, and when memory writes are allowed.
Use cxf search when a human wants to test the same evidence pack an agent will receive:
cxf search "how does auth load user profiles?" --workspace . --budget 2000
The MCP server remains the agent interface. The CLI is for setup, inspection, and repeatable local tests.
Privacy
V1 is local-only. It does not call external embedding APIs, upload source code, edit source files, auto-fix code, or install dependencies inside the target workspace.
Evidence Refs
Memory writes require evidence references returned by search or context packs:
file:src/auth.ts:10-40symbol:src/auth.ts#AuthService:12pack:ctx_...
Invalid or stale evidence is rejected or marked stale.
Contextful MCP questions
How do I add Contextful MCP to Claude Code?
Run claude mcp add contextful -- npx -y @inferensys/contextful in your terminal. Add --scope user to make it available in every project.
How do I add Contextful 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 Contextful MCP provide?
It exposes 7 tools, including context_pack, search_code, trace_path, impact_analysis, why_changed.
What is Contextful?
Contextful is a runtime contextual layer and local search engine for agents that helps them find, compress, cite, and remember project context.
Is my code sent to external servers?
No, the tool is local-only and does not upload source code or call external embedding APIs.
How does the memory system work?
Agents can store lessons and project facts in a memory ledger that requires evidence references from files, symbols, or commits to prevent loose notes.
Which coding tools are supported?
It integrates with Codex, Claude Code, Cursor, Windsurf, GitHub Copilot, VS Code, Cline, Roo Code, Continue, and Zed.