infimium

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()

Requires Node.js 22.5+. From your project folder:

cd /path/to/your/project npx infimium@latest setup

Run 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, pullsnomic-embed-text, indexes the current project or workspace, runsdoctor, and opens Playground.

The published CLI keeps its executable entrypoint, so MCP clients can launch it directly through the configuration below.

npx infimium@latest setup --install-deps

infimium setupcreates one global config at~/.infimium/.env. You do not need a.envin 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_key

Fullinfimium plangeneration also needs a local text model:

infimium plan --dry-run "your task"works without this model and shows the retrieved code context first.

Cursor, Windsurf, Claude Desktop, and other MCP clients:

{ "mcpServers": { "infimium": { "command": "npx", "args": ["-y", "infimium", "serve"] } } }

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, passproject_pathonce; Infimium remembers the active project and auto-indexes it.

Usenpx infimium ...if you did not install the package globally.

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 decision

Infimium uses the localllama3.1model when available and falls back to deterministic compaction when it is not. Raw compacted events remain stored locally for seven days before pruning.get_contextnever calls an LLM or network service.

From a source checkout, build once and run the local playground with:

- 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.

Run the normal index command from a folder containing related projects:

Infimium detects immediate project roots from files such aspubspec.yaml,package.json,Cargo.toml, andgo.mod. It shows the detected roles and dependencies, asks once, then createsinfimium.workspace.json, indexes every project, and opens Playground.

Use--no-workspaceto index only the current project. Workspace projects keep separate memory and Git state whileget_contextincludes balanced summaries and graph relationships from related projects.

Infimium drops the initial payload cost from approximately1,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 withexpand_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:

OpenToken Economicsto see the estimated token difference across your actual indexed symbols.

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_completed
- doctor_run,doctor_passed
- index_started,index_completed,setup_completed
- serve_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.

Where islayer.md?When you runinfimium get-context, it intentionally prints the context directly to your terminal (stdout) so AI agents can read it instantly. It doesn't create alayer.mdfile in your workspace to avoid clutter. If you want to manually save it to a file, use terminal redirection:

Why does the Playground UI say "Awaiting first agent interaction..."?TheCURRENT TASKtracker at the top of the Playground UI is designed to mirror exactly what your AI agent sees. If an agent hasn't queried the context yet (via theget-contexttool), it waits. To force it to update, manually runinfimium get-context.

How do I formatinfimium remember?Theinfimium remembercommand requires a message and a--typeflag (valid types:note,progress,decision,blocker,index,plan). If you also want it to update the active task in the Playground, include the--taskflag:

infimium remember "Added rate limiting" --type progress --task "Security Features"

If you seeFailed 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 runinfimium indexmanually in one terminal whileinfimium playgroundorinfimium watchis still running in another. Simply stop the running process (Ctrl+C) before running manual commands.

Every 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.

SeeCONTRIBUTING.md. Adding a language starts with a parser fixture and extraction test.

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB