Connect your agent

immutlex speaks MCP, the protocol your coding agents already use for tools. Once connected, your agent can search its own knowledge base, follow links between documents, and pull in the right context on its own.

There are three ways to connect. Pick one.

Stdio

The agent starts immutlex itself. Add this to your MCP client config, using the full path to the binary you unpacked:

{
  "mcpServers": {
    "immutlex": {
      "command": "/home/you/.immutlex/immutlex-mcp-server",
      "args": []
    }
  }
}

On Windows, point at immutlex-mcp-server.exe and escape the backslashes:

{
  "mcpServers": {
    "immutlex": {
      "command": "C:\\Users\\you\\.immutlex\\immutlex-mcp-server.exe",
      "args": []
    }
  }
}

Put immutlex.toml and .env.license next to the binary so it finds your storage settings and key without extra configuration.

HTTP

Start the daemon once and let everything share it:

./immutlex-mcp-server --http --config immutlex.toml

Then point your client at it:

{
  "mcpServers": {
    "immutlex": {
      "type": "http",
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

This is the mode to use when you also want the desktop or web app open, since they connect to the same daemon and show you exactly what your agent sees.

Wrapper

Connecting your agent gives it the ability to search. It does not guarantee the agent will remember to. On a long session an agent often stops calling tools and drifts along on whatever is left in its context window.

immutlex-shell closes that gap. Start your agent through it:

./immutlex-shell -- claude
./immutlex-shell -- codex
./immutlex-shell -- copilot

Anything that runs in a terminal works; there is no list of supported agents. The wrapper runs your agent exactly as before, and every fifth time you press Enter it quietly pastes a short summary of your knowledge base in front of what you typed. The agent reads it as if you had typed it yourself, so no tool call is involved and it works even with agents that have no MCP support at all.

Note the --. Everything after it is your agent’s own command line, so its flags stay its own:

./immutlex-shell -- claude --model opus

On Windows, use immutlex-shell.exe from PowerShell or Command Prompt:

.\immutlex-shell.exe -- copilot

Tuning it

Two files next to the binary control the wrapper, and both ship in this bundle:

To inject more or less often, edit inject_every_n_submits in immutlex.toml. Setting it to 0 turns injection off, leaving the wrapper a plain pass-through.

context_anchor.toml is where you decide what the agent is reminded of: a block of fixed text (project rules, invariants) plus live snapshots of your knowledge base. It is capped in both characters and tokens, so it cannot quietly grow into your context budget.

If you delete context_anchor.toml, the wrapper still runs your agent normally but injects nothing.

If something looks wrong

Your terminal is handed to the agent unchanged, so full-screen agents, arrow keys, Ctrl-C and paste all behave as usual, and resizing the window resizes the agent. If the wrapper cannot reach the daemon for a live snapshot it warns once on stderr and carries on rather than interrupting your session.

Where the config file lives

Any other MCP client works too; the two shapes above are all there is. The wrapper needs no client config at all — it works by running the agent, not by being registered with it.

Check that it worked

Restart your agent, then ask it something only your knowledge base would know:

What do we have on pricing?

If the agent answers from your documents, you are connected. If the tools appear locked, your license key has not been found: see troubleshooting.

You can also confirm from the command line:

./immutlex status --config immutlex.toml

Connecting from another machine

Do not open the daemon to the internet. Forward the port over SSH instead:

ssh -N -L 3001:127.0.0.1:3001 you@your-server

Then point the client at http://127.0.0.1:3001/mcp as usual. Only someone who can already log into that server can reach it. See self-hosting.

The Python route

If you are writing Python rather than wiring an agent, skip MCP entirely and call immutlex in your own process:

pip install ./immutlex-*.whl

from immutlex import ImmutlexClient, InjectMode

client = ImmutlexClient.open("immutlex.toml", "default")
context = client.inject_substrate(prompt, max_chars=4096, mode=InjectMode.RECALL)
model_input = f"{context}\n\n{prompt}"

It reads the same license and storage settings as everything else.