infimium
OfficialInfimium is a local-first AI context layer for codebases. It gives AI agents token-efficient access to code, memory, and web tools.
Health:
hello_infimiumchecks server status.Semantic code search:
semantic_code_searchfinds code by meaning and returns compact signatures (~99.5% token reduction).Symbol expansion:
expand_symbolloads full symbol implementation on demand.Dependency graph:
dep_graphinspects imports, callers, callees, and HTTP routes.Project context:
get_contextprovides a tri-zonal YAML/JSON context layer (repo overview, Git state, active task) without network or LLM calls.Project memory:
project_memorymanages persistent memory across sessions—remember progress, resume tasks, complete items, and search history.Local docs search:
query_local_docssemantically searches indexed Markdown, text, HTML, and PDF files.Implementation planning:
plangenerates code-aware plans with an optional dry-run to preview retrieved context.Web search:
web_searchsearches the web (requires optional Tinyfish config).URL fetch:
fetch_urlextracts readable text/markdown from any URL.Shell:
shellruns allowlisted commands with configurable timeouts and output limits.
Key highlights: 100% local, embedded SQLite storage, supports JavaScript, TypeScript, Python, Dart, Go, Rust, Java, and works with any MCP client.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@infimium semantic code search for pricing logic"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Infimium
The Private Context Layer & Super Brain for Your Codebase. Give AI agents persistent memory, deep dependency graphs, and instant code context -- 100% local, zero token bloat.
Demo

Related MCP server: LocalNest MCP
Why
Large repositories make agents read too much code or miss the right symbol. Infimium retrieves compact, relevant context before the agent starts editing.
200,000 lines of code
Agent reads everything -> context blown + expensive
grep "price calculation" -> misses calcPropertyValue()tool: semantic_code_search
query: "price calculation logic"
-> services/property/calc.ts:142 · calcPropertyValue()
-> callers: getListingPrice(), estimatePropertyTax()Quick Start
Requires Node.js 22.5+. From your project folder:
cd /path/to/your/project
npx infimium@latest setupRun setup from the repository you want to index, not from your home directory (~).
Infimium stops broad roots automatically so it cannot scan unrelated files.
That creates global config, starts Ollama if it is installed, pulls nomic-embed-text, indexes the current project or workspace, runs doctor, and opens Playground.
The published CLI keeps its executable entrypoint, so MCP clients can launch it directly through the configuration below.
If Ollama is not installed yet:
npx infimium@latest setup --install-depsinfimium setup creates one global config at ~/.infimium/.env. You do not need a .env in every project. Code, docs, memory, graphs, and vectors are stored locally under ~/.infimium/.
Web search is optional. Add a Tinyfish key only when you need it:
SEARCH_PROVIDER=tinyfish
SEARCH_API_KEY=your_keyFull infimium plan generation also needs a local text model:
ollama pull llama3.1infimium plan --dry-run "your task" works without this model and shows the retrieved code context first.
Connect Your Agent
Cursor, Windsurf, Claude Desktop, and other MCP clients:
{
"mcpServers": {
"infimium": {
"command": "npx",
"args": ["-y", "infimium", "serve"]
}
}
}Restart the client, then use:
Use Infimium hello_infimium.
Use Infimium get_context before starting.
Use Infimium semantic_code_search to explain this repository.Infimium normally uses the MCP process working directory. If your client starts it elsewhere, pass project_path once; Infimium remembers the active project and auto-indexes it.
Tools
Tool | What it does |
| Confirms the MCP server is healthy. |
| Reads saved YAML repo context, current memory and handoff; explicit refresh updates Git/index state. |
| Refreshes episodic memory and handoff graphs; controls automatic memory checkpoints. |
| Finds code by meaning and returns symbol signatures first. |
| Loads one full implementation only when needed. |
| Searches local Markdown, text, HTML, and PDF files. |
| Shows imports, callers, callees, and HTTP routes for a symbol. |
| Keeps active scratchpad events, compact milestones, and durable project rules across agents. |
| Builds a grounded implementation plan from code and graph context. |
| Searches the web through optional Tinyfish configuration. |
| Extracts readable Markdown or text from a URL. |
| Runs allowlisted commands with timeouts and output limits. |
CLI
Command | Description |
| Run health checks on your dependencies and setup. |
| Show the current status of the index and memory. |
| Shows all relevant cli commands. |
| Launch the local web UI to explore index, graph, and memory. |
| Scan and index the current project directory (code, docs, dependencies). |
| Run the indexer in watch mode to continuously index changes. |
| Output the full flattened context as YAML ( |
| Semantically search code and return symbol signatures. |
| Fetch the full implementation code for a specific symbol. |
| Semantically search local markdown/text documentation. |
| Show dependencies, callers, callees, and route graph. |
| Draft an implementation plan based on a given prompt. |
| Add a milestone, progress, or decision to project memory. |
| Show the active task and recent scratchpad memory events. |
| Compact the active scratchpad into an archived milestone. |
| Semantically search past project rules and memory ledger. |
Use npx infimium ... if you did not install the package globally.
Project Memory
Refresh memory yourself, or enable periodic checkpoints for the current project:
infimium update --note "Implemented login validation" --task "Finish login" --handoff "Run the auth tests next"
infimium update start --interval 300
infimium update status
infimium update stopReplace the example notes with your own. Add --project /path/to/repo to select a project and --file src/auth.ts to attach a relevant file. infimium_update and infimium-update are CLI aliases. MCP agents use the infimium_update tool with action: refresh|start|stop|status, project_path, and optional note, task, handoff, files, or interval_seconds.
Auto-update is opt-in and runs while the foreground CLI watcher or an MCP server is open. Its per-project setting survives restarts; stop disables future checkpoints (an in-flight refresh may finish). Checkpoints link episodes, tasks, file references, and handoff notes in local SQLite. Unchanged observations are deduplicated. Automatic checkpoints record observable state, not guessed intent, and never mark a task complete.
get-context / get_context now reads saved context and current memory without rescanning the repo. It includes a bounded memory graph and guidance to answer repo-overview questions only when asked, using Infimium memory first. Missing context is reported explicitly. Run infimium update or get-context --refresh to refresh filesystem context. These are agent guidelines, not an enforcement mechanism for other clients.
Infimium keeps memory bounded across long sessions:
Scratchpad: recent events for the active task.
Archive: compact summaries of completed tasks.
Ledger: durable decisions, rules, quirks, and unresolved blockers.
Record meaningful progress while working:
infimium remember "Added rate-limit middleware" --type progress --task "Rate limiting"
infimium remember "Use Redis-backed counters in production" --type decisionWhen the task is complete:
infimium memory completeInfimium uses the local llama3.1 model when available and falls back to deterministic compaction when it is not. Raw compacted events remain stored locally for seven days before pruning. get_context never calls an LLM or network service.
From a source checkout, build once and run the local playground with:
npm run build
npm run playgroundLocal Architecture
Ollama creates embeddings on your machine.
Embedded SQLite stores vectors, index metadata, project memory, and graph edges. No ChromaDB or Docker service is required.
Documents use recursive boundary-aware chunks instead of blind fixed slices.
JavaScript, TypeScript, Python, and Dart parsers are bundled.
Go, Rust, and Java Tree-sitter WASM grammars download on first use and cache in
~/.infimium/grammars/..gitignore,.infimiumignore, and framework defaults exclude dependencies, build output, Flutter artifacts, caches, and binaries before indexing.semantic_code_searchreturns signatures;expand_symbolprovides full code on demand.Project memory uses session-scoped scratchpads, compact milestone archives, and a versioned semantic ledger.
get_contextemits static anchors, dynamic repository state, and active execution as separate YAML zones.
Multiple Projects
Run the normal index command from a folder containing related projects:
infimium indexInfimium detects immediate project roots from files such as pubspec.yaml, package.json, Cargo.toml, and go.mod. It shows the detected roles and dependencies, asks once, then creates infimium.workspace.json, indexes every project, and opens Playground.
For unattended setup:
infimium index --yes --no-playgroundUse --no-workspace to index only the current project. Workspace projects keep separate memory and Git state while get_context includes balanced summaries and graph relationships from related projects.
Infimium - Playground
Infimium drops the initial payload cost from approximately 1,460 tokens to 8 tokens per symbol. Semantic search returns the AST signature first; the agent requests the full implementation only when it needs it with expand_symbol.
Full implementation ~1,460 tokens
AST skeleton ~8 tokens
Initial payload reduction ~99.5%These are Playground reference values, not a claim that every function has the same size. Inspect your own indexed repository and compare AST-first retrieval with full-text retrieval locally:
infimium playgroundOpen Token Economics to see the estimated token difference across your actual indexed symbols.
Privacy
Code, docs, embeddings, memory, graph data, prompts, queries, file paths, and repo names remain local.
Infimium sends privacy-safe anonymous lifecycle telemetry so we can understand setup success:
init_started,init_completeddoctor_run,doctor_passedindex_started,index_completed,setup_completedserve_started,first_tool_call,playground_opened
Telemetry includes an anonymous install ID, Infimium version, OS, Node major version, timestamp, and event name. It never includes code, file paths, repo names, prompts, search queries, memory notes, API keys, or user identity.
Disable it anytime:
infimium telemetry offor set:
INFIMIUM_TELEMETRY=falseTroubleshooting
FAQ & Common Confusions
Where is layer.md?
When you run infimium get-context, it prints saved context directly to your terminal (stdout). Refreshes store project-scoped YAML under Infimium's local data directory. To export the saved context to a file, use terminal redirection:
infimium get-context > layer.mdWhy does the Playground UI say "Awaiting first agent interaction..."?
The CURRENT TASK tracker reflects stored project context. Run infimium update --task "Your task" to refresh it; get-context reads the saved snapshot.
How do I format infimium remember?
The infimium remember command requires a message and a --type flag (valid types: note, progress, decision, blocker, index, plan). If you also want it to update the active task in the Playground, include the --task flag:
infimium remember "Added rate limiting" --type progress --task "Security Features"Database is locked
If you see Failed to start Infimium: Database is locked, it means another instance of Infimium is actively holding a lock on the SQLite memory database. This usually happens if you try to run infimium index manually in one terminal while infimium playground or infimium watch is still running in another. Simply stop the running process (Ctrl+C) before running manual commands.
General Setup Issues
Run:
infimium doctorEvery failed check prints one copy-paste fix. If setup still fails, give this prompt to your coding agent:
Set up Infimium in this repository. Install/start Ollama, pull nomic-embed-text,
run npx infimium init, run npx infimium index, and make all six
npx infimium doctor checks pass. Do not commit secrets.Contributing
See CONTRIBUTING.md. Adding a language starts with a parser fixture and extraction test.
Self-hosting is free forever under the MIT license.
Available Tools
11 toolsdep_graphC
Inspect dependency relationships for a symbol.
Inputs: symbol_name (required), project_path.
expand_symbolB
Load the full implementation of one symbol returned by semantic_code_search.
Inputs: symbol_name (required), file_path, project_path.
fetch_urlC
Fetch a URL and extract readable content.
Inputs: url (required), extract.
get_contextA
Read the balanced YAML context layer with repo overview, Git state, task, memory, and AST-first handoff guidance. Pass project_path once to activate the current IDE workspace as the default.
Inputs: limit, format, refresh, project_path.
hello_infimiumB
Health probe for the Infimium MCP server.
Inputs: no named parameters.
planC
Generate a grounded implementation plan for the current repository.
Inputs: task (required), top_k, dry_run, language, +3 more.
project_memoryB
Manage compact project memory across chats, agents, and IDEs: remember active work, complete and archive sessions, search history, or update durable rules.
Inputs: key, note, task, limit, +7 more.
query_local_docsC
Query indexed local documentation.
Inputs: query (required), top_k, project_path.
semantic_code_searchC
Search code semantically and return compact symbol signatures.
Inputs: query (required), top_k, language, project_path.
shellC
Run an allowlisted shell command.
Inputs: command (required), cwd, timeout.
web_searchC
Search the web for current information.
Inputs: query (required), max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a clearly distinct function: context reading, health probe, web search, URL fetching, local docs, semantic code search, symbol expansion, dependency graph, shell execution, planning, and project memory. There is no overlap or ambiguity between them.
Naming is inconsistent: some tools use verb_noun (web_search, fetch_url, expand_symbol), while others are bare nouns (shell, plan), abbreviations (dep_graph), or greetings (hello_infimium). This mixed style makes the set harder to predict and navigate.
With 11 tools, the server is well-scoped—each tool earns its place and the count is within the ideal 3-15 range. It feels comprehensive without being bloated.
The tool surface covers a broad workflow: context, code exploration, web/docs lookup, shell access, planning, and memory. Slight gaps like a direct file editor exist, but shell can fill in, so the coverage is nearly complete.
Maintenance
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server for semantic code search & navigation that helps AI agents work efficiently without burning through costly tokens. Instead of reading entire files, agents can search conceptually and jump directly to the specific functions, classes, and code chunks they need.122MIT
- AlicenseBqualityDmaintenanceA local-first MCP server that provides AI agents with safe codebase access through file discovery, hybrid lexical-semantic search, and project introspection. It features durable local memory and semantic indexing while keeping all data and processing entirely on your local machine.7427 npm6MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents structured code understanding and precise code intelligence via local indexing of AST, call graphs, and semantic search.73 npm4Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides structure-aware code analysis (symbol trees, dependencies, docs) to reduce AI agent token consumption by up to 99%, along with Git commit intelligence.MIT