Infimium Agent

Private search MCP for AI agents. Web · code · local docs · dependency graph — one endpoint, your machine.

[](https://www.npmjs.com/package/infimium) [](LICENSE) [](https://github.com/infimium-ai/infimium-agent)

The problem

Agents need precise context, but large repos make that expensive fast. Keyword search is brittle: it misses intent, aliases, and the symbols that actually matter.

200,000 lines of code
Agent reads everything → 💀 context blown + $$$
grep "price calculation" → misses calcPropertyValue()

With Infimium

Infimium indexes your docs, code symbols, and dependency graph locally. Agents ask focused tools for the right context instead of reading the whole project.

tool: semantic_code_search
query: "price calculation logic"

→ services/property/calc.ts:142 · calcPropertyValue()
→ imported by: listing.ts, tax.ts, pdf-generator.ts, calc.test.ts

Tools

web_search — Brave web search with retry and concise source snippets.

fetch_url — fetches HTML, strips noise, returns Markdown or text.

query_local_docs — local document RAG over .md, .txt, .html, and .pdf.

semantic_code_search — differentiator: tree-sitter symbols + local embeddings for meaning-based code search.

dep_graph — differentiator: SQLite import graph for "where is this defined and who imports it?"

shell — allowlisted command runner with blocked patterns, timeout, and output caps.

plan — differentiator: retrieves semantic code context and dependency edges, then drafts an implementation plan.

status — CLI health check for indexed docs, code symbols, dep graph relationships, watched projects, DB size, and last index time.

doctor — CLI setup check for Node/npm, Ollama, ChromaDB, .env, and index readiness.

Why self-hosted

Your code index, your embeddings, your dep graph — all on your machine. Nothing leaves.

• Embeddings run locally with Ollama.
• No vendor lock-in: MCP, SQLite, ChromaDB, TypeScript.
• Works in air-gapped environments.

Quick start

git clone https://github.com/infimium/infimium && cd infimium
cp .env.example .env  # add your SEARCH_API_KEY
./scripts/setup.sh

Setup guide

npm package

Requires Node.js 22.5+.

Install:

npm i infimium

Create .env:

cp .env.example .env

Configure:

SEARCH_API_KEY=your_brave_api_key
SEARCH_PROVIDER=brave
LOCAL_DOCS_PATH=/absolute/path/to/docs
CODEBASE_PATH=/absolute/path/to/code
OLLAMA_HOST=http://localhost:11434
CHROMADB_HOST=http://localhost:8000
SHELL_ALLOWLIST=ls,git,npm,npx

Start Ollama:

ollama serve
ollama pull nomic-embed-text

Start ChromaDB on http://localhost:8000:

chroma run --path ./chroma_db --host localhost --port 8000

Or with Docker:

docker run -p 8000:8000 -v ./chroma_db:/chroma/chroma chromadb/chroma

Index docs and code:

npx infimium index

Check status:

npx infimium status

Check setup health:

npx infimium doctor

Generate a grounded implementation plan:

npx infimium plan --dry-run "add rate limiting to the auth endpoint"
npx infimium plan --write "add rate limiting to the auth endpoint"

Serve MCP:

npx infimium serve

infimium status is not hardcoded. It reads local SQLite metadata and ChromaDB counts. If it shows 0 files, run npx infimium index after setting LOCAL_DOCS_PATH and CODEBASE_PATH.

Docker

cp .env.example .env

Set:

SEARCH_API_KEY=...
LOCAL_DOCS_PATH=./docs
CODEBASE_PATH=./code

Run:

./scripts/setup.sh

The setup script starts ChromaDB, starts Infimium, pulls nomic-embed-text, runs indexing, and prints the MCP config.

Local development

Install dependencies:

npm install

Requires Node.js 22.5+.

Start Ollama:

ollama serve
ollama pull nomic-embed-text

Start ChromaDB on http://localhost:8000.

Create .env:

cp .env.example .env

Use local paths:

LOCAL_DOCS_PATH=/absolute/path/to/docs
CODEBASE_PATH=/absolute/path/to/code
OLLAMA_HOST=http://localhost:11434
CHROMADB_HOST=http://localhost:8000

Index:

npm run index

Serve:

npm start -- serve

Check status:

npm run status

Check setup:

npm run doctor

Plan a code change:

npm run plan -- --dry-run "add rate limiting to the auth endpoint"

Tool brief

| Tool | Input | Requires | Output | | --- | --- | --- | --- | | web_search | query, max_results | Brave API key | ranked web results | | fetch_url | url, extract | network access | cleaned Markdown/text | | query_local_docs | query, top_k | indexed docs, Ollama, ChromaDB | matching document chunks | | semantic_code_search | query, language, top_k | indexed code, Ollama, ChromaDB | matching symbols with file and line range | | dep_graph | symbol_name | indexed code graph | definition file, importers, imports | | shell | command, cwd, timeout | allowlisted command | stdout, stderr, exit code | | plan | task, dry_run, write_plan, output_path, top_k, language | indexed code, Ollama, ChromaDB | implementation plan or retrieved context | | status | none | local SQLite/ChromaDB state | index health summary | | doctor | none | local environment | setup pass/fail report |

Use the tools

After adding Infimium to Claude Desktop, Cursor, or Windsurf, ask the agent to use a specific Infimium tool by name. The MCP client sends the JSON input to Infimium; you do not call these tools with HTTP.

web_search

Use it for current web results.

Prompt:

Use Infimium web_search to find recent MCP server examples.

Tool input:

{
  "query": "recent MCP server examples",
  "max_results": 5
}

Requires:

SEARCH_API_KEY=...
SEARCH_PROVIDER=brave

fetch_url

Use it to fetch a page and extract readable content.

Prompt:

Use Infimium fetch_url to fetch https://modelcontextprotocol.io and summarize it.

Tool input:

{
  "url": "https://modelcontextprotocol.io",
  "extract": "markdown"
}

extract can be markdown or text.

query_local_docs

Use it after indexing local documents.

Prompt:

Use Infimium query_local_docs to find setup instructions for ChromaDB.

Tool input:

{
  "query": "ChromaDB setup instructions",
  "top_k": 5
}

Before using:

LOCAL_DOCS_PATH=/absolute/path/to/docs
npm run index

semantic_code_search

Use it to find code by meaning instead of exact text.

Prompt:

Use Infimium semantic_code_search to find the price calculation logic.

Tool input:

{
  "query": "price calculation logic",
  "language": "typescript",
  "top_k": 5
}

Before using:

CODEBASE_PATH=/absolute/path/to/code
npm run index

language is optional. Supported values depend on indexed files: javascript, typescript, python.

dep_graph

Use it to see where a symbol is defined, who imports it, and what its file imports.

Prompt:

Use Infimium dep_graph for calcPropertyValue.

Tool input:

{
  "symbol_name": "calcPropertyValue"
}

Before using:

CODEBASE_PATH=/absolute/path/to/code
npm run index

shell

Use it for safe, allowlisted local commands.

Prompt:

Use Infimium shell to run git status.

Tool input:

{
  "command": "git status",
  "cwd": "/absolute/path/to/repo",
  "timeout": 30
}

Allow commands explicitly:

SHELL_ALLOWLIST=ls,git,npm,npx

Blocked patterns include rm -rf, sudo, curl, wget, eval, and inline code execution.

plan

Use it before editing code. It retrieves semantically relevant symbols, enriches them with dependency edges, and asks the local LLM for a safest-first implementation plan.

CLI dry run:

npx infimium plan --dry-run "add rate limiting to the auth endpoint"

Generate and write plan.md:

npx infimium plan --write "add rate limiting to the auth endpoint"

Tool input:

{
  "task": "add rate limiting to the auth endpoint",
  "dry_run": false,
  "write_plan": true,
  "output_path": "plan.md",
  "top_k": 5
}

Before using:

npx infimium doctor
npx infimium index

Use --dry-run to inspect retrieved context without calling the LLM. If the context is bad, re-index before judging plan quality.

status

Use it from the terminal to inspect local index health.

npm run status

doctor

Use it first when setup feels broken.

npx infimium doctor

It checks, in order:

1. Node/npm version compatibility
2. Ollama installed and running
3. nomic-embed-text pulled
4. ChromaDB reachable
5. .env and required keys
6. whether the current repo has been indexed

Every failed check includes one copy-pasteable fix command. The command exits 1 if anything fails, so it works in scripts.

Example output:

───────────────────────────
  Infimium status
───────────────────────────
  Docs         47 files · 312 chunks
  Code         847 symbols · 124 files
  Dep graph    312 relationships
  Projects     2 watched
  DB size      2.1 MB
  Last indexed 2 hours ago
───────────────────────────

Connect to Claude Desktop

{
  "mcpServers": {
    "infimium": {
      "command": "npx",
      "args": ["infimium", "serve"],
      "env": {
        "SEARCH_API_KEY": "your_brave_search_api_key",
        "LOCAL_DOCS_PATH": "/absolute/path/to/docs",
        "CODEBASE_PATH": "/absolute/path/to/code",
        "OLLAMA_HOST": "http://localhost:11434",
        "CHROMADB_HOST": "http://localhost:8000"
      }
    }
  }
}

Connect to Cursor / Windsurf

{
  "mcpServers": {
    "infimium": {
      "command": "npx",
      "args": ["infimium", "serve"],
      "env": {
        "SEARCH_API_KEY": "your_brave_search_api_key",
        "LOCAL_DOCS_PATH": "/absolute/path/to/docs",
        "CODEBASE_PATH": "/absolute/path/to/code",
        "OLLAMA_HOST": "http://localhost:11434",
        "CHROMADB_HOST": "http://localhost:8000"
      }
    }
  }
}

Pricing

Self-host free forever (MIT). Need us to run it for you?

infimium.ai — starts at $12/mo, 14-day trial, no free hosted tier.

Paid hosted glimpse:

• Managed indexing workers for large repos and doc sets.
• Hosted project memory and plan.md generation.
• Team dashboards for index freshness, tool usage, and failures.
• Priority language/parser support.

Contributing

[CONTRIBUTING.md](CONTRIBUTING.md)

Adding a new language? Start here.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: infimium-ai
• Source: infimium-ai/infimium-agent
• License: MIT
• Homepage: https://infimium.com

Install and usage instructions live in the source repository linked above.