![\"Replay](\".github/demo-reasoning.svg\")
\n\n \n
That is scripts/demo_reasoning.py, abridged. Every line is an\nasserted behaviour that runs in CI, so this picture cannot quietly stop being true.
\n ![\"The](\".github/omem-demo.gif\")
\n
Two sources disagree. Neither is overwritten.\nSee the whole thing running.
\n\n## What makes it different\n\nMost agent memory is a list of facts. When two facts conflict, one silently\noverwrites the other and the history is gone. OMEM keeps both, tracks which one\nis currently believed, and can tell you why. A few things it does that a plain\nvector store does not:\n\n- **Belief state over time.** Every fact has a state (believed, contradicted,\n unknown) that the engine computes from the evidence, not a static row.\n- **Contradiction handling.** Conflicting information is surfaced, not lost.\n Claims named `X` and `not:X` are treated as opposed automatically; for anything\n else, `mem.contradict(\"prefers_annual\", \"prefers_monthly\")` says so once. OMEM\n never decides two claims disagree by reading them, because that judgment is\n what would stop the same question having the same answer a year later.\n- **Provenance.** Ask why something is believed and get the chain that led there.\n- **Cross-agent memory.** Memory is private to an agent by default; you choose\n what to share with a team or the whole project.\n- **Semantic recall.** Finds relevant memories even when the wording differs\n from how they were stored. Works offline with a dependency-free embedding;\n set `OMEM_EMBED_MODEL` to use your provider's real embedding model, with\n cached vectors and automatic fallback if the provider is down.\n- **A learning loop.** Memories that prove useful rank higher over time.\n- **Self-healing that refuses.** OMEM records failures and runs repairs under\n policy, and will not run a repair nobody authorised. A model can propose a\n plan; only actions registered in code execute, and risk class comes from\n OMEM's registry rather than from the plan claiming its own. See\n [Self-healing](#self-healing).\n\n## Quick start\n\nYou need Python 3.9 or newer. No other dependencies.\n\n**Option 1: install from PyPI (server included).**\n\n```bash\npip install omem-infrastructure\nomem-server\n```\n\nUpgrading from an earlier version? `pip install --upgrade omem-infrastructure`.\nPlain `pip install` on a package you already have reports \"Requirement already\nsatisfied\" and does nothing, which is a quiet way to keep running the version\nyou were trying to leave. `python -c \"import omem; print(omem.__version__)\"`\nsays what you actually have.\n\nThat starts the server on http://127.0.0.1:8787 and, on first run, prints a\nproject id and an API key: no signup call, no dashboard visit, nothing to\nconfigure. Paste them straight in:\n\n```python\nfrom omem import Memory\n\nmem = Memory(api_key=\"omem_sk_...\", base_url=\"http://127.0.0.1:8787\",\n project=\"proj_...\")\nmem.remember(agent=\"support\", about=\"customer:1\", claim=\"prefers_annual_billing\")\nprint(mem.believes(about=\"customer:1\", claim=\"prefers_annual_billing\"))\n# -> BELIEVED_TRUE\n```\n\n**[QUICKSTART.md](QUICKSTART.md)** takes that to a contradiction and a provenance\nchain in about five minutes, which is where the difference from a vector store\nactually shows.\n\n**Option 2: run from this repo.**\n\n```bash\ncd server\npython api.py # or: python api.py 9000 for a different port\n```\n\nSame server, same first-run project id and key, started from source. Setup takes\nabout a minute either way. Two differences worth knowing:\n\n- **The database lands in a different place.** From source it is\n `server/data/omem.db`; `omem-server` writes `./omem-data/omem.db` in whatever\n directory you ran it from. `OMEM_DB` overrides either.\n- **The dashboard needs building once.** The wheel ships a built copy; a clone\n does not, so the server prints \"dashboard not bundled\" until you run\n `cd web && OMEM_STATIC=1 npm run build`. The API is identical either way.\n\n**Option 3: Docker.**\n\n```bash\ndocker run -p 127.0.0.1:8787:8787 -p 127.0.0.1:3000:3000 \\\n -v omem-data:/app/server/data ghcr.io/troybrandonc-bit/omem\n```\n\nAPI on 8787, dashboard on 3000, data in the named volume. The ports are\npublished to loopback on purpose: the container runs in local mode, which has\nno passwords, so reachability is the access control. Putting it on a network\nmeans setting `OMEM_AUTH=password` and `OMEM_MASTER_KEY` first, and\n`docker-compose.yml` in this repo shows that shape.\n\n## Self-healing\n\nOMEM records what breaks and repairs it under policy. This is infrastructure for\nyour agents, not something OMEM does to itself: you register a component and the\nhooks it can be repaired with, and OMEM owns the memory, the safety boundary and\nthe lifecycle.\n\nThe part that matters is what it refuses. A model may *propose* a repair plan;\nOMEM decides what is permitted. Only action types registered in code can execute,\nrisk class comes from that registry and never from the plan, high-risk actions\nneed explicit approval, and a repair is not successful until it verifies.\n\n```python\nmem.healing.report_health(\"vector-index\", \"healthy\", \"12,400 vectors\")\n\nresult = mem.healing.handle(\n error={\"component\": \"vector-index\", \"error_type\": \"StaleShard\"},\n plan={\"diagnosis\": \"replica fell behind after a partition\",\n \"confidence\": 0.8,\n \"actions\": [{\"type\": \"rebuild_index\"}, {\"type\": \"exec_shell\"}]},\n)\nresult[\"status\"] # -> \"denied\"\nresult[\"decisions\"] # rebuild_index: permitted (low risk)\n # exec_shell: unknown action type (not registered)\n```\n\nNothing ran. The plan is kept with the reason each action was permitted or\nrefused, so the refusal is a record rather than a silence. Error text and model\noutput are data here, and neither can name an action into existence.\n\nEverything else you would want is enforced too: failures are fingerprinted so a\nthousand identical errors are one entry, a repair storm is capped per component,\none recovery per component is claim-enforced in the database, secrets are\nstripped before anything is persisted, and an internal error escalates rather\nthan retrying wild.\n\nThe **Self-healing** screen in the dashboard shows component health, the failure\nrecord, and how far each repair got, with the step it stopped at marked, and the\ndiagnosis it acted on. `server/healing.py` is the whole subsystem and is worth\nreading if you are deciding whether to trust it.\n\n## The dashboard\n\nThe dashboard ships inside the package. Start the server and open the same\naddress, **http://127.0.0.1:8787**. It is all there: memory, conflicts, the\nbelief graph, the timeline, logs and the audit trail. No Node, no second\nprocess, no second port.\n\nIn local mode (the default) there is no login; it opens on the project the\nserver created for you. On a server running `OMEM_AUTH=password` it shows a\nsign-in form instead.\n\nIt is a static export of `web/`, the only UI in this repository, copied into the\nwheel at build time. To work on it:\n\n```bash\ncd web\nnpm install\nnpm run dev # http://localhost:3000, proxying to the API on 8787\n```\n\nand to rebuild the bundled copy, `OMEM_STATIC=1 npm run build`.\n\n## Authentication\n\nOMEM runs in one of two modes, and the difference matters before you put it\nanywhere other than your own machine.\n\n**`OMEM_AUTH=local`**: the default, and what makes the quickstart a minute.\nThere is no login: the dashboard provisions a session against the server it can\nsee. That is only safe while nothing else can reach the server, so local mode\n**refuses to bind a non-loopback address**. If you mean it (a container whose\nports are published to `127.0.0.1`, a single-user VM), set\n`OMEM_ALLOW_INSECURE_BIND=1`.\n\n**`OMEM_AUTH=password`**: required for a server other people can reach.\nAccounts have passwords, hashed with PBKDF2-SHA256. Signing up with an address\nthat already has a password returns 409 rather than a session, TOTP is enforced\nwhere it is enrolled, and the server refuses to start unless `OMEM_MASTER_KEY`\nis set to something other than its development default.\n\n```bash\nexport OMEM_AUTH=password\nexport OMEM_MASTER_KEY=\"$(python3 -c 'import secrets;print(secrets.token_urlsafe(32))')\"\nomem-server\n```\n\n### TLS\n\nPoint `OMEM_TLS_CERT` and `OMEM_TLS_KEY` at a certificate and the server speaks\nHTTPS itself (TLS 1.2 floor). Setting only one is a startup error, not a quiet\nfall back to plaintext. A terminating proxy is still better at scale, but\nrunning without one no longer means running in the clear.\n\n### Encrypting memory at rest\n\n```bash\npip install \"omem-infrastructure[encryption]\"\nexport OMEM_ENCRYPT_AT_REST=1\nexport OMEM_MASTER_KEY=\"$(python3 -c 'import secrets;print(secrets.token_urlsafe(32))')\"\n```\n\nEncrypts the operations log, ingested source payloads and the quoted evidence\nbehind each memory with AES-GCM. Existing plaintext rows keep working, so it can\nbe switched on for a database that already has data. It refuses to start on the\ndevelopment master key, and refuses to run without a real AEAD library rather\nthan falling back to the stdlib keystream used for OAuth tokens.\n\n**Lose the key and the data is gone**: there is no recovery path, and no\nrotation tooling yet.\n\n## When two entities are one person\n\nFormation mints entity ids from what it can see, so one human can arrive\ntwice: `person:sarah_chen` from a sentence in a message body,\n`person:sarah_chen@acme` from writing the mail. Each id holds half the beliefs\nabout one person, and they can neither corroborate nor contradict each other.\n\n```bash\ncurl -X POST \"$OMEM/v1/memory/resolve?project=$PROJECT\" \\\n -H \"Authorization: Bearer $KEY\" -d '{}'\n```\n\nDecisive evidence merges: the same full name in the same organisation, which\nis the rule formation itself already applies within one path. The merge is a\nrecorded coreference by `agent:omem-resolution` with a derivation to its\nanchors, so `/why` explains it and a split undoes it. Suggestive evidence\n(\"Sarah\" against \"Sarah Chen\" at acme) becomes a proposal in\n`GET /v1/memory/merge-proposals` that changes nothing until a person approves\nit -- and the approval is recorded under the approver's name, not the\nmachine's.\n\nThe refusals are the feature: never across organisations, never without one,\nnever on conflicting surnames or role vocabulary, never when ambiguous, and\nnever re-merging what a split separated. Pass `{\"apply\": false}` for a dry\nrun that records nothing. From the SDK it is `mem.resolve()`,\n`mem.merge_proposals()`, and `mem.approve_merge(id, agent=...)`; the\ndashboard's **Proposals** screen is the same queue with buttons.\n\n## Rules that conclude, and take it back\n\nContradiction is declared, never inferred from text. Inference works the same\nway: a rule is data you declare, and the machine composes exactly what you\nsaid and nothing else.\n\n```bash\ncurl -X POST \"$OMEM/v1/rules?project=$PROJECT\" -H \"Authorization: Bearer $KEY\" \\\n -d '{\"when\": [{\"rel\": \"works_at\", \"dir\": \"fwd\"}, {\"rel\": \"owns\", \"dir\": \"rev\"}],\n \"then\": {\"rel\": \"involves\", \"dir\": \"rev\"}}'\ncurl -X POST \"$OMEM/v1/memory/infer?project=$PROJECT\" \\\n -H \"Authorization: Bearer $KEY\" -d '{}'\n```\n\nSarah works at Beta; Acme owns Beta; OMEM concludes Acme's orbit involves\nSarah -- as an ordinary assertion derived from the exact premises it used, so\n`/why` walks from the conclusion to the evidence, and as a real graph edge, so\nrecall reaches it in one hop.\n\nThe reason to want this is what happens on the way down. Retract the\nownership and the conclusion is withdrawn in the same request; a conclusion\nresting on that conclusion falls after it. Every withdrawal is an ordinary\nretraction in the op log. Evidence is spent once -- a conclusion you close is\nnever re-litigated from the same premises -- and a deactivated rule's\nconclusions are withdrawn on the next pass.\n\nAll of it is a script rather than a paragraph, same contract as the refusal\ndemo below -- every behaviour asserted, non-zero exit if one stops holding,\nrun in CI:\n\n```bash\npython3 scripts/demo_reasoning.py\n```\n\n## Shapes that ask questions\n\nTwo beliefs conflict only over the same subjects, which is what keeps belief\nstate reproducible -- and it means \"Sarah works at Acme\" and \"Sarah works at\nBeta\" never contradict. Whether that is fine is domain knowledge, so you\ndeclare it:\n\n```python\nmem.declare_constraint(\"works_at\", \"one_dst_per_src\") # one employer at a time\nmem.check()\n```\n\nA violation becomes a tension in the Proposals queue. OMEM does not pick the\nnewer employer: you name the one that survives (the rest are retracted under\nyour name, and anything the rules engine concluded from them falls in the\nsame request), or dismiss it, which is permanent for exactly that evidence.\nThe machine never nags twice about a question a person already answered.\n\n## Hunches with case files\n\nHumans learn from one example by leaping to conclusions. That reflex is also\nwhy human memory confabulates. OMEM keeps the speed and drops the\nconfabulation: it leaps, and then it doubts the leap harder than you would.\n\n```python\nmem.leap() # one similar case is enough\nmem.expects(about=\"customer:gamma\")\n# -> wants_pdf_invoices, strength 0.35, \"beta holds it; gamma resembles\n# beta (both prefer annual billing, both use crm)\", docket attached\nmem.interrogate() # the skeptic works every open case\n```\n\nA hypothesis is never a belief. It never enters the engine, `believes()`\nstays UNKNOWN however good the hunch, and only reality about the target can\nsupport or refute it -- look-alikes just move strength. Verdicts teach: a\nsource whose leaps keep being confirmed generates stronger hunches, one\nthat keeps being wrong generates weaker ones, and a refuted leap is never\nmade again from the same evidence. A case that will not resolve starts\nasking, and the question lands on the dashboard where a yes or no becomes\nreal evidence under your name -- the verdict still comes from\ninterrogation, never by decree.\n\nResemblance works the way human analogy does: one rare shared trait binds\nharder than three common ones, differently-worded experience counts as the\nsame experience when an embedding model is configured, and shared context\nweighs less than shared character. And `mem.calibration()` is the\nmetacognition: OMEM knows which kinds of claims it guesses well, and its\nboldness follows its record.\n\n## Priors: what it learns about people in general\n\nA leap projects from one look-alike person. A prior projects from a\nregularity learned across many: \"people who hold P tend to hold Q.\" OMEM mines\nthese from what it already knows and uses them to interpret someone new from\nvery little.\n\nA pair is kept only where holding P measurably moves the odds of Q beyond how\ncommon Q is on its own, and that test is applied to the lower bound of the\nrate rather than the rate itself, so a pattern resting on a handful of people\nmust be far cleaner than one resting on hundreds.\n\n```python\nmem.learn_priors() # mine regularities across everyone\nmem.priors()\n# -> holds likes_dashboards -> holds wants_pdf_invoices\n# in_population: 41 of 52 wants_pdf_invoices on its own: 0.29\n# kept because the lower bound of that rate clears 0.29, not\n# because wants_pdf_invoices happens to be common\n# when_applied: supported 3, refuted 0\n```\n\nThat rule replaced one that asked only whether sixty per cent of the holders\nof P also held Q. Measured against 19,668 real respondents with a known latent\nstructure, the old rule recovered that structure at 0.185 where chance is\n0.184: it was selecting consequents by how common they were. The current rule\nrecovers it at 0.875, using 94% fewer priors that cover more claims than\nbefore. The study is\n[Working Paper No. 1](https://machinetestimony.org/papers/wp1/) and the harness\nis in [`benchmarks/external/`](benchmarks/external/).\n\nThe point is that a prior never overrides a person. It fires only into a\nsilence: if someone holds P but has said nothing about Q, OMEM leaps Q onto\nthem as a hunch; the moment that person's own evidence speaks, the prior is\nrefused, and if their evidence later contradicts an accepted hunch, the\ninterrogate loop refutes it and the prior takes the loss. Two honest numbers\ntravel with every prior: the rate it held in the population it was learned\nfrom, and its separate record when actually applied. A pattern seen on too\nfew people is not allowed to fire at all.\n\nA prior stores counts, never a person. It is knowledge about people in\ngeneral with no fact about anyone in it, which is what lets you read the\nwhole set, or hand it to someone, without leaking a single subject. The\ngeneral pattern always yields to the individual, by construction rather than\nby policy.\n\n## Everyday behaviour is memory too\n\nNot everything worth remembering is a contract. \"Mornings work best for me\",\n\"email is the best way to reach me\", \"I don't work Fridays\" are the small\nrepeated preferences of ordinary correspondence, and OMEM extracts them\noffline, no LLM required. A first-person sentence attaches to the person who\nwrote it, the same node their employment is inferred onto from the address\nthey write from, while \"we prefer async\" stays a fact about the company. A\nrole address like support@ never mints a fake person, and every habit\ncarries the sentence it came from as evidence. These are exactly the\nregularities the priors tier generalises: \"people who prefer mornings\nusually prefer email\" is a learned pattern, not a guess.\n\n## The right to be forgotten, executed\n\nRetraction is not erasure: an append-only log keeps history, and a real\nerasure request means the personal data is gone. `POST\n/v1/entities/{id}/forget` rewrites the op log for real: every record that\nreferences the person, everything that cascaded from those, the events that\ncarried only their words, and the evidence quotes, edges, hypotheses and raw\nsource messages behind them. A sentence of theirs quoted under a surviving\nbelief is redacted, because the sentence is the person's even when the\nbelief is a company's. The pruned log is replay-verified through a scratch\nengine before anything is touched, and what remains afterwards is one row\nholding a hash, counts and a date: proof the erasure happened, retaining\nnothing. It is an admin act, it asks for explicit confirmation, and it\ncannot be undone.\n\n## The commons, and what it will never take\n\nOn first open the dashboard asks one question: contribute anonymous\npatterns to the shared OMEM commons? What leaves the machine if you say yes\nis counts, like \"held for 5 of 7\". Never a name, a company, a message, or a\nnumber from your data; the exact file sits on your own disk to inspect, and\neither answer is revocable in Settings. Silence sends nothing, forever.\nThe commons pools those counts across consenting installations to study\nhuman working behaviour in general. Anonymity is structural at both doors:\na contribution carrying anything identifying is refused on arrival, so the\npool cannot leak what it never held.\n\n## Teaching AI what people are like\n\nThe commons exists for one objective: to connect humans and AI by giving AI\na better understanding of our nature and behaviour. Models today learn\nabout people from scraped text that was never offered and that names\neveryone in it. The commons is the opposite offer: regularities in how\npeople actually work, contributed on purpose, holding nobody.\n\nIt ships as a training corpus. One JSON line per pattern carries the counts\nand a plain-English rendering (\"subjects who prefer morning meetings\nusually also prefer email contact: 24 of 31 with a stance, 77%\"), with a\ndataset card stating the provenance, the consent story, and the license,\nCC BY 4.0 with attribution to the OMEM commons. A model trained on it\nlearns the rate, never a person, and the card says the operative sentence\nout loud: rates are population tendencies, never rules about individuals.\nA real person can and will contradict any of them, and a system that\nrespects people treats every pattern as a prior that yields to the\nindividual, the same way OMEM itself does.\n\n## What changed while you were gone\n\nThe question every agent asks at session start, answered from the same as_of\nmachinery every query already uses:\n\n```python\nd = mem.changes(since=last_seen)\n```\n\nBeliefs that appeared; beliefs that closed, each saying how -- superseded\nand by what, or withdrawn; conflicts newly opened and newly resolved;\nreferents that merged or split. Read-only, deterministic, and scope-safe:\nyour diff contains only what you could have recalled.\n\n## Seeing what it refuses\n\nThe self-healing boundary is the part that is hard to believe from a\ndescription, so it is a script rather than a paragraph:\n\n```bash\npython3 scripts/demo_refusal.py\n```\n\nIt drives a real server through the two ways a repair plan actually goes wrong.\nA model proposes `reload_config` (registered) alongside `exec_shell` (not\nregistered anywhere): the first is permitted on its merits, the second is\nrefused by name, and the plan as a whole is denied. A plan that claims its own\nrisk class gets it ignored, because risk comes from the registry. An\ninstruction embedded in the error message the model read executes nothing.\nEvery verdict is kept and readable afterwards, and a secret in the error\ncontext is not in storage.\n\nRegistration happens in code. There is no API that adds an executable action\ntype, so no plan and no prompt widens what is permitted.\n\nEvery refusal in it is asserted and it exits non-zero if one stops happening,\nso it runs in CI. A demo that can quietly become untrue is worse than none.\n\n## The Witness benchmark\n\nMemory benchmarks measure recall. [Witness](benchmarks/witness/) measures\nthe opposite duty: does a memory system assert things nobody told it, keep\nrepeating what was withdrawn, silently resolve disagreements, merge two\npeople who share a name, or hold on to conclusions whose premises died?\n\nSix scenarios, ten axes, deterministic scoring, no LLM judges. Adapters are\nincluded for OMEM, Mem0 and Graphiti; each system is fed through its own\nnative path, and a probe a system cannot express reports as unsupported\nrather than passed or failed. This repository publishes no numbers it did\nnot run: OMEM's card, every probe passing on every axis, is asserted by\n`server/tests_witness_benchmark.py` against a live server on every commit.\nRun the others with your own keys and read your own card.\n\n## The claims ledger\n\nMarketing that cannot fail is indistinguishable from marketing that is\nfalse. [CLAIMS.md](CLAIMS.md) maps every load-bearing sentence this project\nsays about itself to the executable statement that would go red if it\nstopped being true, and the ledger is itself guarded in CI: a row whose\nfile goes missing fails the build.\n\nTwo rows worth calling out because nobody else in this niche can write\nthem. *It phones home to nobody*: `tests_airgap.py` installs a guard under\nthe socket layer, then drives every major feature through a live server and\nfails on a single outbound connection or DNS lookup that is not loopback.\n*Upgrades never rewrite your past*: a log frozen on 2026-08-29 replays to a\nbyte-identical state digest on every commit, so no future version can\nquietly reinterpret a history you already recorded.\n\n## Proving the state follows from the log\n\nMemory is rebuilt by replaying an append-only log. That is easy to claim and\nwas not checkable from outside, which is a weak place for a project whose whole\nargument is that you can reconstruct what an agent believed and why.\n\n```bash\nomem-verify\n```\n\n```\nproj_a14ce3f94fab My first project\n replayed 4 operations -> 2 assertions, 2 propositions\n state digest cd95d761079a2388...\n deterministic yes\n```\n\nIt replays the log into two independent fresh engines and compares the\nresulting state. A difference would mean replay depends on something outside\nthe log, and that the same question does not give the same answer.\n\nThat check cannot detect tampering, because a rewritten log replays perfectly\nconsistently with itself. For that, record a digest and keep it somewhere OMEM\ncannot write:\n\n```bash\nomem-verify --record # writes .omem-state.json\nomem-verify --anchor kept-elsewhere.json\n```\n\n```\n anchor DOES NOT MATCH cd95d761079a2388... the log has changed\n audit chain org_f4f3bdfa7a82 MISMATCH\n```\n\nThe same file anchors the **audit chain head**, for the same reason. That chain\nis tamper-evidence rather than tamper-proofing: someone with write access can\nrewrite it from the edit forward and it stays internally consistent. Only a head\nhash kept where OMEM cannot reach it detects that. Two anchors in two places is\ntwo habits, and the one you skip is the one that mattered.\n\nIt proves the state follows from the log, and that neither the log nor the audit\nchain has changed since the anchor. It does not prove the beliefs are correct,\nor that nothing was removed before the first anchor was taken.\n\n### The bill of materials\n\n```bash\npython3 scripts/gen_sbom.py > sbom.json # CycloneDX\npython3 scripts/gen_sbom.py --check # fails if a runtime dep appears\n```\n\nThe server and the SDK have **no runtime dependencies**, so the SBOM is one\ncomponent and the transitive surface is the standard library. The optional\nextras are listed and marked optional, because \"no dependencies\" would\notherwise be a half-truth. `--check` runs in CI so the claim cannot quietly\nstop being true.\n\n## Refusing ungrounded writes\n\nEvery belief carries a grounding verdict: `GROUNDED` if its provenance reaches a\nrecorded event, `UNGROUNDED` if it only ever rests on other claims. That verdict\nis returned on every read, so a caller can filter on it.\n\nFiltering only helps the caller who remembers to filter. Set\n`OMEM_REQUIRE_GROUNDED=1` and OMEM refuses the write instead:\n\n```bash\nOMEM_REQUIRE_GROUNDED=1 omem-server\n```\n\n```python\nmem.remember(agent=\"support\", about=\"customer:1\", claim=\"prefers_annual\")\n# -> 422 R_UNGROUNDED: cite `because` evidence that reaches a recorded event\n\nmem.remember(agent=\"support\", about=\"customer:1\", claim=\"prefers_annual\",\n because=[\"evt_call_2026_08_26\"]) # accepted\n```\n\nEvidence counts if it is a recorded event, or an assertion that is itself\ngrounded, so a chain of reasoning that bottoms out in something observed is\nadmitted while a chain that bottoms out in nothing is not.\n\nIt applies to direct writes. Supersede and retract replace a claim that already\npassed admission and inherit its provenance, and the ingestion path has always\nhad its own gate: every candidate is graded before the engine sees it, and\n`DO_NOT_STORE` and `LOW` never become assertions.\n\nOff by default, because it is a real constraint on how you write and existing\ncallers should not break on upgrade.\n\n## What is in this repo\n\n- `server/` is the OMEM server: an HTTP API wrapping the memory engine. The\n engine itself lives in `server/omem_engine/` and is the source of truth for all\n memory decisions.\n- `sdk/python/` is the Python SDK and the `omem-server` / `omem-mcp` commands.\n It is the one that is published: `pip install omem-infrastructure`.\n- `sdk/typescript/` is the TypeScript SDK, published as\n **`npm install @omem/sdk`**. It lags the Python SDK, and it builds and tests\n itself against a real server:\n\n ```bash\n cd sdk/typescript\n npm install && npm test # builds, then runs test_parity.mjs against a live server\n ```\n\n `test_parity.mjs` starts the Python server, drives the built SDK against it and\n reports what is missing. Closing that gap is the most useful contribution\n available right now.\n- `web/` is the dashboard.\n\n## Use it from LangChain\n\nOMEM implements LangGraph's `BaseStore`, which is how LangChain agents hold\nlong-term memory:\n\n```bash\npip install \"omem-infrastructure[langgraph]\"\n```\n\n```python\nfrom omem import Memory\nfrom omem.integrations.langgraph_store import OmemStore\n\nstore = OmemStore(Memory(api_key=\"omem_sk_...\", project=\"proj_...\"))\nstore.put((\"memories\", \"alice\"), \"pref\", {\"text\": \"prefers annual billing\"})\nstore.get((\"memories\", \"alice\"), \"pref\").value\n# -> {\"text\": \"prefers annual billing\"}\n```\n\nPass it to `create_react_agent(..., store=store)` or any LangGraph graph, the\nsame as `InMemoryStore`.\n\n![\"26-second](\".github/omem-langgraph-ad.gif\")
\n\nThe difference from the built-in stores is what happens on the second write.\nThey overwrite, and `delete` erases. Here a `put` over an existing key\n**supersedes**: the previous value stays on the record with the moment it\nstopped being believed, and `delete` **retracts** rather than destroys. Every\nwrite is attributed, so `mem.why(assertion_id)` answers where a memory came\nfrom. That costs a network round trip per operation, which is the trade.\n\nVector search on the store is not implemented yet. `search()` filters by\nnamespace and by field; passing `query=` raises rather than quietly returning a\nsubstring match dressed as semantic search.\n\n## Use it from an MCP client\n\nInstalling the package gives you an `omem-mcp` command that speaks MCP over\nstdio, so MCP clients like Claude Desktop can use OMEM as a memory tool:\n\n```bash\npip install omem-infrastructure\n```\n\nThen, in your MCP client's config, the whole entry is:\n\n```json\n{ \"mcpServers\": { \"omem\": { \"command\": \"omem-mcp\" } } }\n```\n\nNo key, no URL, no separate server to start. On first run it starts the bundled\nserver itself, creates a project, and remembers it in `~/.omem`. Restarting the\nclient reuses the same memory.\n\nTen tools. Five are the record: `omem_recall`, `omem_observe`,\n`omem_remember`, `omem_why` and `omem_believes`. Five are the intuition layer,\nall reads: `omem_expects` (what OMEM suspects and does not believe, with its\ncase file), `omem_priors` (the regularities it has learned about people in\ngeneral), `omem_brief` (one call at the start of a task, instead of assembling\nthe same picture from four others), `omem_ask` (one question, answered from what this install has seen itself\nfirst and the commons second, each labelled with the people and installations\nit rests on), and `omem_weigh` (weigh a belief you already hold against the\npopulation).\n\n`omem_ask` refuses rather than returning nothing when too few people support an\nanswer, because \"no such pattern\" and \"too few people to say\" are different\nanswers and an agent acts differently on each. It reads from disk: the commons\nsnapshot is already here, so asking works with the commons unreachable or never\ncontacted at all.\n\nThere is no tool that promotes a hypothesis, answers its open question, or\ntriggers a leap. A hunch takes its verdict from reality during interrogation,\nand a model does not get a lever that marks one true by saying so. Anything\n`omem_expects` lists still reads `UNKNOWN` through `omem_believes`, and a test\nasserts exactly that.\n\n`observe` hands OMEM raw conversation and lets it decide what is durable, which\nis what you want over a transcript. `remember` records a fact you have already\nidentified:\n\n```json\n{\"about\": \"customer:acme\", \"claim\": \"prefers_dark_mode\",\n \"because\": \"said on the 3 Nov call\"}\n```\n\nUse `remember` when you know the fact. Extraction runs a deterministic\nvocabulary aimed at decisions and commitments, so a claim outside it records\nnothing at all, and a model naming a claim is not a model deciding what is\ntrue: OMEM still owns belief state, contradiction and provenance.\n\nIdentity is fixed by the environment, never by a tool argument, on both axes\nthat scope memory: `OMEM_AGENT` is the agent whose memory this is, and\n`OMEM_USER` is the end user it is acting for. A model speaking MCP cannot name\neither, so it cannot ask for another agent's or another user's private memory.\n`OMEM_USER` is optional; leave it unset and no user-scoped memory is visible,\nwhich is the right default for a process that has not been told who it acts for.\n\nTo wire it into Claude Desktop, start `omem-server` once to get a project id and\nkey, then add this to `claude_desktop_config.json` and restart the app:\n\n```json\n{\n \"mcpServers\": {\n \"omem\": {\n \"command\": \"omem-mcp\",\n \"env\": { \"OMEM_AGENT\": \"claude\", \"OMEM_USER\": \"you@example.com\" }\n }\n }\n}\n```\n\nBoth of those are optional. `OMEM_AGENT` names the agent whose memory this is\nand `OMEM_USER` the end user it acts for; neither is a tool argument, so a model\ncannot name either one. Point it at a server you already run by setting\n`OMEM_API_KEY`, `OMEM_BASE_URL` and `OMEM_PROJECT` instead, and explicit\nconfiguration always wins over the bundled one.\n\nThe config file lives at `~/Library/Application Support/Claude/claude_desktop_config.json`\non macOS and `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows.\n\n## Status and price\n\nFree, and free while it stays in beta: no plans, no card, no quota.\n\nThis is early software under active development. It is meant for testing and\nfeedback right now.\n**[The security page](https://infrastructure.omem-cloud.com/security)** lists\nwhat it protects and, just as importantly, what it does not yet: no SSO, no\ncertifications, no key rotation, an audit chain that detects tampering rather\nthan preventing it, and one process holding authoritative state, enforced now,\nso a second one refuses to start rather than diverging, but that is the honest\nabsence of high availability rather than the presence of it. Read that before\nyou plan around it. If you try it and something breaks or feels wrong, that feedback is\nexactly what is useful at this stage.\n\n## License\n\nMIT. See `LICENSE`.\n\n---\n\nDevelopment history and detailed engine notes are in `CHANGELOG-dev-notes.md`,\n`ENGINE.md`, and `ENGINE_VALIDATION.md`.\n",
"bytes": 37834,
"sha": "d4324aa1fafcc13d3745fc674c933480d154e4ac9ba26be1a22a901b47a26c9f",
"repo_slug": "troybrandonc-bit/omem",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_troybrandonc_bit_omem_430762c6/readme"
}