Using it well

immutlex changes how you prompt. That shift is the whole point, and it is worth ten features. This page is the short version of what people learn after a few weeks.

Ask the substrate, then prompt

The old habit is to stuff everything into the prompt: here is the codebase, here is the spec, here is the conversation history, now answer me. The bill is enormous and the model has to find the answer inside a wall of undifferentiated noise.

The new habit is to ask a short question and let immutlex attach the few most relevant pieces before the model ever reads it.

The knowledge base is the working memory. The prompt is the question.

Most people still put working memory in the question. That is the inefficiency worth eliminating. Once it clicks, your prompts get shorter and the answers get better.

Write to it constantly

immutlex compounds. It gets more useful the more of your real work lands in it, so make writing cheap and frequent.

Two shapes cover almost everything:

Fire and forget for the steady stream: conversation turns, emails, meeting notes, tickets, chat messages, decisions as you make them. These should never block whatever your app is doing. If immutlex is slow for an hour, that is a monitoring problem, not a user-facing failure.

Blocking for bulk work where the next step depends on the last: transcripts, document trees, schema imports. When you push a set of documents that reference each other, send them as one batch so their links resolve together.

When a write succeeds, it is really there

A successful ingest means the document is chunked, embedded, indexed, and queryable in the graph. Not “accepted and probably fine.”

So you do not need to push, wait, then search to check it landed. If something fails on the way in, you get an error saying so. Delete that verification loop if you have one.

Give each document a stable name

Every document has a source path, and that path is how immutlex knows whether something is new or an update.

• Same path, same content: nothing happens. It is already there.
• Same path, new content: a new revision, with the old one kept.
• New path: a new document.

So use a stable path for things that evolve (clients/acme/profile) and a unique one for things that happen once (email/2026-03-14/<id>). Never put a timestamp in the path of something you intend to update, or you will get a new copy every time instead of a history.

Any path shape works. It does not need to look like a filename.

Trust the automatic context

If your agent is set up to receive context automatically, do not also fetch it by hand. Writing “search, then paste the results, then call the model” defeats the point, and you pay for the same context twice.

Let the model decide when it needs more. It can go looking mid-answer when the question turns out to be deeper than it looked. That is the correct division of labour: the system supplies the baseline, the model asks for more.

Search explicitly when you want one specific fact. Trust the automatic context when you are answering a question.

The catch is that all of this depends on the agent choosing to ask. On a long session it often stops: it settles into whatever is already in its window and answers from there, confidently, without ever touching the knowledge base. You usually notice only when it repeats something you corrected an hour ago.

If you are working in a terminal, start the agent through the wrapper and the decision stops being the agent’s:

./immutlex-shell -- <your agent>

Every few turns immutlex hands it a short briefing whether it asked or not. It costs a bounded number of tokens per injection, capped in context_anchor.toml, and it is the difference between an agent that has memory and one that had it at the start of the session. Use it for long working sessions; for one-off questions it does not matter much.

Curate, do not delete

The instinct to clean up is usually wrong here.

Knowledge that stops being useful should fade, not disappear. immutlex ranks less relevant material lower over time, so it stops crowding your results while remaining part of the record. You can also mark something as noise, or push it back up when it matters again.

This is why the knowledge base stays sharp over months instead of turning to mud. Let that maintenance run. If something you expected did not surface, look at why it ranked low before you reach for deletion.

There is a delete for the rare case you truly need it, but reach for fading and marking first. Nearly every time, that is the right answer.

One brain, many surfaces

The most common mistake at scale is giving each agent its own memory. Do not.

Point every agent at the same knowledge base. A conversation captured by one agent in the morning should inform a different agent’s answer that afternoon. That only happens if they share a substrate.

If you need separation between teams or clients, use separate vaults rather than separate systems. One daemon, several isolated views, each with its own access rules.

Habits to avoid

• Putting working memory into the prompt.
• Searching before every single turn when context is already being supplied.
• Verifying an ingest by searching for it afterwards.
• Writing status reports into a repo where they quietly go stale. Put them here instead, where they fade on their own.
• Giving each agent its own private memory cache.
• Deleting documents that have merely gone quiet.
• Turning off maintenance because something moved in the rankings.
• Treating it as a vector store. Retrieval is one part; the links between documents are what make answers good.
• Trusting a writer’s own success log instead of asking immutlex directly.

Check on it

One command tells you what you need:

./immutlex status --config immutlex.toml

Documents in the graph, orphans, broken links, whether storage is reachable, and whether anything is stuck. Look here first when an answer seems wrong; usually something never made it in.

What good looks like

After a few weeks of real use, you should see shorter prompts, cheaper answers, and a model that stops confidently inventing things about your own domain. It will not make hallucinations vanish, and anyone claiming otherwise is overselling. What it does is remove the class of mistake that comes from the model simply not knowing what you already wrote down.