This is an alpha-stage context engine that indexes your codebase once and returns ranked, cited evidence packs instead of making agents repeatedly read dozens of files. It exposes seven MCP tools, anchored by context_pack(query, budget, scope), which replaces scattered grep and file read calls with a single token-budgeted response. You also get search_code forlex/BM25 search, trace_path for graph traversal across symbols and modules, impact_analysis for reverse dependencies, and write_lesson for storing evidence-backed memory that persists across sessions. Uses SQLite with FTS5 for local-only indexing. Set it up with npx @inferensys/contextful init, then run it as an MCP server. Reach for this when context window bloat and redundant file reads are slowing down your agent workflows.
⚠️ 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.
Context has always been a bottleneck for agentic AI. Large context window models (for example, 1M tokens) are:
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:
The default local store is SQLite with FTS-backed search and typed graph tables. V1 ships with:
nodes, edges, node_props, edge_props.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.
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.
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.
Contextful is an MCP server, local indexer, and small 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.
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
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
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.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
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.
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.
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.
io.github.ericm1018/skillfm-llm-cost-optimizer-openai-anthropic-usage
io.github.mikerawsonnz/llm-orchestration-agent
io.github.mikerawsonnz/authenticated-llm-agent
labforgedev/copilot-memory-mcp
csoai-org/agent-prompt-injection-firewall-mcp
io.github.mikerawsonnz/authenticated-multi-llm-agent