infimium

Infimium

Private context layer for AI coding agents. Search code and docs, inspect dependencies, preserve project memory, and build grounded plans from one local MCP server.

Demo

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

1,460 Tokens -> 8

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 playground

Open Token Economics to see the estimated token difference across your actual indexed symbols.

Quick Start

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

npx infimium@latest setup

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.

If Ollama is not installed yet:

npx infimium@latest setup --install-deps

infimium 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_key

Full infimium plan generation also needs a local text model:

ollama pull llama3.1

infimium 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
hello_infimium	Confirms the MCP server is healthy.
get_context	Loads tri-zonal YAML context: stable repo anchors, live Git/index state, and active execution.
semantic_code_search	Finds code by meaning and returns symbol signatures first.
expand_symbol	Loads one full implementation only when needed.
query_local_docs	Searches local Markdown, text, HTML, and PDF files.
dep_graph	Shows imports, callers, callees, and HTTP routes for a symbol.
project_memory	Keeps active scratchpad events, compact milestones, and durable project rules across agents.
plan	Builds a grounded implementation plan from code and graph context.
web_search	Searches the web through optional Tinyfish configuration.
fetch_url	Extracts readable Markdown or text from a URL.
shell	Runs allowlisted commands with timeouts and output limits.

CLI

infimium doctor
infimium status
infimium playground
infimium index
infimium watch
infimium get-context
infimium code-search "authentication middleware"
infimium expand-symbol authenticateUser
infimium docs-search "deployment setup"
infimium dep-graph authenticateUser
infimium plan --dry-run "add rate limiting"
infimium remember "Rate limiter tests pass" --type progress --task "Rate limiting"
infimium resume
infimium memory complete
infimium memory search "rate limiting decision"

Use npx infimium ... if you did not install the package globally.

Project Memory

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

When the task is complete:

infimium memory complete

Infimium 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 playground

Local 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_search returns signatures; expand_symbol provides full code on demand.
• Project memory uses session-scoped scratchpads, compact milestone archives, and a versioned semantic ledger.
• get_context emits 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 index

Infimium 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-playground

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

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

Disable it anytime:

infimium telemetry off

or set:

INFIMIUM_TELEMETRY=false

Troubleshooting

Run:

infimium doctor

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.

Contributing

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

Self-hosting is free forever under the MIT license.