OMEM

OMEM

The system of record for what an AI agent believed and did. Append-only, with the evidence under every belief, both sides of every contradiction kept, and a named human behind every risky action. So when an agent acts and someone asks "why did it do that", you answer with a record instead of an investigation.

OMEM sits where a memory layer sits and does a different job. Instead of dumping text into a vector store and hoping for the best, it tracks what each agent believes over time, keeps the evidence under every belief, and handles contradictions explicitly, so an agent can reason about what it knows, when it learned it, and why it holds.

And it does not start from nothing. Installs that choose to pool what they work out about people in general, as counts that name nobody, and a young install borrows that intuition on day one instead of spending six months earning it. What you contribute is counts; what you get back is everyone else's. A borrowed pattern is born weaker than one you learned yourself, and still yields the moment a person's own evidence disagrees, so the general never overrides the individual.

The bank is empty today. No installation has contributed yet, which means the first ones decide what it learns, and it is worth knowing that a corpus of regularities about people can carry the biases of whoever filled it. The mining rule was rebuilt so that a pattern has to beat the base rate rather than ride it (Working Paper No. 1); whether the contributing population is representative is a separate question and an open one.

It runs locally with no external services and no dependencies to install.

pip install omem-infrastructure && omem-server

Or deploy a private server in one click:

The blueprint provisions one small service with a persistent disk, password auth on (the first signup is the operator account), and a generated master key. Fly.io works too: fly launch --copy-config with the included fly.toml.

Docs: [infrastructure.omem-cloud.com](https://infrastructure.omem-cloud.com) · Quickstart · Security · Contributing

Shipping agents to clients? The audit trail and the approval gate are the

point: what a client's security review asks for,

and a small number of hands-on design-partner pilots are open.

Want to see the whole pattern run before reading another word?

refund-desk is the

reference integration: a support agent that moves money, with receipts.

One file, runs in a minute, asserts every claim it makes.

That is scripts/demo_reasoning.py , abridged. Every line is an asserted behaviour that runs in CI, so this picture cannot quietly stop being true.

Two sources disagree. Neither is overwritten. See the whole thing running .

What makes it different

Most agent memory is a list of facts. When two facts conflict, one silently overwrites the other and the history is gone. OMEM keeps both, tracks which one is currently believed, and can tell you why. A few things it does that a plain vector store does not:

• Belief state over time. Every fact has a state (believed, contradicted, unknown) that the engine computes from the evidence, not a static row.
• Contradiction handling. Conflicting information is surfaced, not lost. Claims named X and not:X are treated as opposed automatically; for anything else, mem.contradict("prefers_annual", "prefers_monthly") says so once. OMEM never decides two claims disagree by reading them, because that judgment is what would stop the same question having the same answer a year later.
• Provenance. Ask why something is believed and get the chain that led there.
• Cross-agent memory. Memory is private to an agent by default; you choose what to share with a team or the whole project.
• Semantic recall. Finds relevant memories even when the wording differs from how they were stored. Works offline with a dependency-free embedding; set OMEM_EMBED_MODEL to use your provider's real embedding model, with cached vectors and automatic fallback if the provider is down.
• A learning loop. Memories that prove useful rank higher over time.
• Self-healing that refuses. OMEM records failures and runs repairs under policy, and will not run a repair nobody authorised. A model can propose a plan; only actions registered in code execute, and risk class comes from OMEM's registry rather than from the plan claiming its own. See Self-healing.

Quick start

You need Python 3.9 or newer. No other dependencies.

Option 1: install from PyPI (server included).

pip install omem-infrastructure

omem-server

Upgrading from an earlier version? pip install --upgrade omem-infrastructure. Plain pip install on a package you already have reports "Requirement already satisfied" and does nothing, which is a quiet way to keep running the version you were trying to leave. python -c "import omem; print(omem.__version__)" says what you actually have.

That starts the server on http://127.0.0.1:8787 and, on first run, prints a project id and an API key: no signup call, no dashboard visit, nothing to configure. Paste them straight in:

from omem import Memory

mem = Memory(api_key="omem_sk_...", base_url="http://127.0.0.1:8787", project="proj_...") mem.remember(agent="support", about="customer:1", claim="prefers_annual_billing") print(mem.believes(about="customer:1", claim="prefers_annual_billing"))

-> BELIEVED_TRUE

[QUICKSTART.md](QUICKSTART.md) takes that to a contradiction and a provenance chain in about five minutes, which is where the difference from a vector store actually shows.

Option 2: run from this repo.

cd server

python api.py # or: python api.py 9000 for a different port

Same server, same first-run project id and key, started from source. Setup takes about a minute either way. Two differences worth knowing:

• The database lands in a different place. From source it is server/data/omem.db; omem-server writes ./omem-data/omem.db in whatever directory you ran it from. OMEM_DB overrides either.
• The dashboard needs building once. The wheel ships a built copy; a clone does not, so the server prints "dashboard not bundled" until you run cd web && OMEM_STATIC=1 npm run build. The API is identical either way.

Option 3: Docker.

docker run -p 127.0.0.1:8787:8787 -p 127.0.0.1:3000:3000 \

-v omem-data:/app/server/data ghcr.io/troybrandonc-bit/omem

API on 8787, dashboard on 3000, data in the named volume. The ports are published to loopback on purpose: the container runs in local mode, which has no passwords, so reachability is the access control. Putting it on a network means setting OMEM_AUTH=password and OMEM_MASTER_KEY first, and docker-compose.yml in this repo shows that shape.

Self-healing

OMEM records what breaks and repairs it under policy. This is infrastructure for your agents, not something OMEM does to itself: you register a component and the hooks it can be repaired with, and OMEM owns the memory, the safety boundary and the lifecycle.

The part that matters is what it refuses. A model may *propose* a repair plan; OMEM decides what is permitted. Only action types registered in code can execute, risk class comes from that registry and never from the plan, high-risk actions need explicit approval, and a repair is not successful until it verifies.

mem.healing.report_health("vector-index", "healthy", "12,400 vectors")

result = mem.healing.handle( error={"component": "vector-index", "error_type": "StaleShard"}, plan={"diagnosis": "replica fell behind after a partition", "confidence": 0.8, "actions": [{"type": "rebuild_index"}, {"type": "exec_shell"}]}, ) result["status"] # -> "denied" result["decisions"] # rebuild_index: permitted (low risk)

exec_shell: unknown action type (not registered)

Nothing ran. The plan is kept with the reason each action was permitted or refused, so the refusal is a record rather than a silence. Error text and model output are data here, and neither can name an action into existence.

Everything else you would want is enforced too: failures are fingerprinted so a thousand identical errors are one entry, a repair storm is capped per component, one recovery per component is claim-enforced in the database, secrets are stripped before anything is persisted, and an internal error escalates rather than retrying wild.

The Self-healing screen in the dashboard shows component health, the failure record, and how far each repair got, with the step it stopped at marked, and the diagnosis it acted on. server/healing.py is the whole subsystem and is worth reading if you are deciding whether to trust it.

The dashboard

The dashboard ships inside the package. Start the server and open the same address, http://127.0.0.1:8787. It is all there: memory, conflicts, the belief graph, the timeline, logs and the audit trail. No Node, no second process, no second port.

In local mode (the default) there is no login; it opens on the project the server created for you. On a server running OMEM_AUTH=password it shows a sign-in form instead.

It is a static export of web/, the only UI in this repository, copied into the wheel at build time. To work on it:

cd web

npm install npm run dev # http://localhost:3000, proxying to the API on 8787

and to rebuild the bundled copy, OMEM_STATIC=1 npm run build.

Authentication

OMEM runs in one of two modes, and the difference matters before you put it anywhere other than your own machine.

`OMEM_AUTH=local`: the default, and what makes the quickstart a minute. There is no login: the dashboard provisions a session against the server it can see. That is only safe while nothing else can reach the server, so local mode refuses to bind a non-loopback address. If you mean it (a container whose ports are published to 127.0.0.1, a single-user VM), set OMEM_ALLOW_INSECURE_BIND=1.

`OMEM_AUTH=password`: required for a server other people can reach. Accounts have passwords, hashed with PBKDF2-SHA256. Signing up with an address that already has a password returns 409 rather than a session, TOTP is enforced where it is enrolled, and the server refuses to start unless `OMEM_MASTE