memoose 0.4.0__tar.gz

memoose-0.4.0/.gitignore

@@ -0,0 +1,28 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+.omc/
+**/results/*/data/
+**/results/*/cwd/
+
+# third-party benchmark dataset, fetched by benchmarks/locomo/fetch_dataset.py
+benchmarks/locomo/locomo10.json
+
+# the Procedural Graphs paper, cited by ADR 0004 as arXiv:2609.09153
+docs/*.pdf
+
+# third-party benchmark datasets, fetched on demand
+benchmarks/longmemeval/longmemeval_s*.json
+
+# LaTeX build artifacts (memoose.bbl is kept: arXiv needs it and does not run BibTeX)
+paper/*
+
+# this machine's agent tooling, not part of memoose (skill managers, host-scoped installs)
+.agents/
+.claude/
+skills-lock.json

memoose-0.4.0/CONTEXT.md

@@ -0,0 +1,129 @@
+# memoose
+
+A dual-path memory system for proactive agents, packaged as an Agent Plugin (skills plus an MCP server). The deterministic parts of memory management are MCP tools; the judgment that other memory libraries delegate to an LLM is described in skills and done by the Host Model as it calls the tools.
+
+## Language
+
+### Actors
+
+**Host**:
+The agent client that installs the plugin and runs the conversation, such as Claude Code or Codex.
+_Avoid_: Provider, client, harness, IDE
+
+**Host Model**:
+The LLM the Host is already running the conversation with. The only model memoose ever uses.
+_Avoid_: LLM, provider model, API model, sampling
+
+**Engine**:
+The MCP server part of the plugin. It stores, indexes, and retrieves memory. It never calls, prompts, or orchestrates a model.
+_Avoid_: Server, backend
+
+### Memory
+
+**Dataset**:
+A named scope that memory belongs to and recall is restricted to. A project directory and a user's global memory are each a Dataset.
+_Avoid_: Namespace, collection, workspace
+
+**Ontology**:
+The declared entity types and relation types that extracted facts are resolved against.
+_Avoid_: Schema, taxonomy, graph model
+
+**Session**:
+One conversation's short-lived memory: turns plus typed context entries, distilled into Lessons when the conversation ends.
+_Avoid_: Thread, chat, conversation log
+
+**Fact**:
+One relation between two entities with a one-sentence description and an evidence pointer. The unit recall returns.
+_Avoid_: Triple, edge, triplet, claim
+
+**Evidence**:
+Where a Fact comes from, as a pointer a later run can re-check: a file range, URL, issue id, or "user said <date>".
+_Avoid_: Source, citation, reference
+
+**Functional Relation**:
+A relation name that holds one current value per subject, such as owned_by. A newer Fact supersedes the older one automatically.
+_Avoid_: Single-valued, cardinality-one, unique relation
+
+**Superseded**:
+The state of a Fact that a newer Fact replaced. It leaves default recall but stays in history.
+_Avoid_: Deleted, archived, stale, outdated
+
+**Contradiction**:
+Two Facts that cannot both be true of the same subject at the same time, recorded with a reason and a confidence until one supersedes the other.
+_Avoid_: Conflict, inconsistency, clash
+
+**Hotspot**:
+A subject that holds several values for one relation. A candidate for a Contradiction or a Functional Relation, not yet judged. A Procedure with several Transitions is a branch, never a Hotspot.
+_Avoid_: Duplicate, collision
+
+**Lesson**:
+A distilled, reusable learning from a Session, stored as an entity linked to what it applies to.
+_Avoid_: Insight, takeaway, note, memory
+
+**Bucket**:
+A group of entities of one type with a written summary; together the Buckets form the global context of a Dataset.
+_Avoid_: Cluster, community, index entry, topic
+
+**Procedure**:
+A step an agent takes, stored as an entity: a tool action, a check, or a state of the work. A Fact answers what is; a Procedure and its Transitions answer what to do next.
+_Avoid_: Workflow, playbook, recipe, step, skill (a skill is the host's instruction file, not memory)
+
+**Transition**:
+A Fact whose source and target are both Procedures. It says the target is admissible after the source, and carries a Condition, an Advice and a Pitfall.
+_Avoid_: Edge, next step, arrow, link
+
+**Condition**:
+The circumstance under which a Transition applies.
+_Avoid_: Precondition, trigger, when-clause
+
+**Advice**:
+How to carry out the target Procedure once a Transition is taken.
+_Avoid_: Guidance (that is the assembled neighbourhood), instruction, how-to, tip
+
+**Pitfall**:
+What went wrong on a Transition before and must be avoided when it is taken again.
+_Avoid_: Warning, anti-pattern, gotcha, failure
+
+**Start**:
+A Procedure that marks the entry of a chain, so the first Position of a task can be localised and a chain can be built from nothing.
+_Avoid_: Root, entry point, begin
+
+**Position**:
+The Procedure the agent is at now, declared on a Session turn. The only signal Guidance is keyed on.
+_Avoid_: Active node, current step, state, location
+
+**Trace**:
+The ordered Positions of one Session, closed by its Outcome. What a later distillation contrasts a failed run against a successful one with.
+_Avoid_: Trajectory, history, log, path
+
+**Outcome**:
+How a Session ended: succeeded, failed, or abandoned. Declared by the agent when the Session ends.
+_Avoid_: Score, result, status, verdict
+
+**Guidance**:
+The Transitions two hops out from the agent's Position, put in front of the agent before it acts. The agent decides; Guidance is memory, not an instruction.
+_Avoid_: Suggestion, plan, next steps, recommendation
+
+**Dismissal**:
+A recorded judgment that a candidate was reviewed and declined, with the reason: a maintenance candidate (a Hotspot, a possible duplicate, a possible connection, an undistilled Session) or a proposed change to a Transition. It removes the candidate from later passes and changes nothing in the graph. Lives in Provenance.
+_Avoid_: Rejection, ignore, mute, suppress
+
+**Provenance**:
+The append-only ledger of every change to memory: who did what to which entity or Fact, and when.
+_Avoid_: Audit log, history table, changelog
+
+## Code layout
+
+`src/memoose/` is three layers plus two entry points. Nothing imports upward.
+
+`harness/` beside it holds what reaches the Host without code: `skills/`, `hooks/`, `agents/`. The plugin manifest and `memoose install` both read from there.
+
+| Package | Holds | Imports from |
+|---|---|---|
+| `store/` | `sqlite_store`, `schema`, `embeddings`, `datasets` (where a Dataset's file lives) | nothing internal |
+| `graph/` | `models`, `ids`, `ontology`, `chunking`, `retrieval`, `contradictions`, `memify`, `sessions`, `procedures` | `store/` |
+| `engine.py` | the `Engine` facade every surface calls | `graph/`, `store/` |
+| `server.py` | MCP tools over `Engine` | `engine`, `graph/` |
+| `cli/` | `main` (the `memoose` command), `integrations` (host installers), `graph_html` (the viewer) | `engine`, `graph/`, `store/` |
+
+Library users import from the top: `from memoose import Engine, EntityIn, RelationIn, OntologyError`.

memoose-0.4.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

memoose-0.4.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.5
+Name: memoose
+Version: 0.4.0
+Summary: A dual-path memory system for proactive agents: facts and procedures in a local graph, exposed as a CLI, MCP tools and skills, no API key.
+Author: Hieu Ngo
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent-plugins,claude-code,codex,knowledge-graph,mcp,memory
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.10
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Provides-Extra: fastembed
+Requires-Dist: fastembed>=0.5; extra == 'fastembed'
+Provides-Extra: ontology
+Requires-Dist: rdflib>=7; extra == 'ontology'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/memoose-mascot.png" alt="the Memoose mascot" width="220">
+
+# Memoose: A Dual-Path Memory System for Proactive Agents
+
+</div>
+
+---
+
+## Contents
+
+- [What is Memoose](#what-is-memoose)
+- [Quick start](#quick-start)
+- [Give your agent memory](#give-your-agent-memory)
+- [How Memoose works](#how-memoose-works)
+- [Usage](#usage): [tools](#tools) · [skills](#skills) · [CLI](#cli)
+- [Benchmarks](#benchmarks)
+- [Learn more](#learn-more): [documentation](#documentation) · [inspiration](#inspiration) · [contributing](#contributing) · [license](#license)
+
+# What is Memoose
+
+**Memoose** is a dual-path memory system for proactive agents. Memory survives the session and
+survives switching agents. It is found two ways: by search when the agent asks, and by
+recommendation when it does not. An **engine** keeps a typed knowledge graph on your machine; a
+**harness** of skills, hooks and tools teaches the model your host already runs how to use it.
+
+It is built for long-lived project work: decisions, conventions and ownership facts that must stay
+correct for months, each with an evidence pointer back to its source.
+
+### Vision
+
+**Memory is upkeep.** Facts are written as they surface. `memoose maintain` sweeps the store into
+one worklist of things to judge and decides nothing itself; a model makes every call, on a small
+subagent that costs neither your attention nor the conversation's turns.
+
+**Search and recommendation are the two ways anything gets found.** Search answers a question you
+thought to ask. Recommendation surfaces what you did not. A search-only memory stays silent unless
+the agent already suspects something is there. Memoose does both: `recall`, and a hint before each
+prompt.
+
+**The context an agent most often lacks is procedural.** It knows what things are and still runs
+steps out of order, skips a check, or repeats a step that already failed. Memoose stores procedures
+as a graph, after Google's [Procedural Graphs](https://arxiv.org/abs/2609.09153): steps as nodes,
+transitions carrying a condition, an advice and a pitfall. The agent declares where it is, reads the
+transitions two hops out, and decides. When the session ends with an outcome, every transition it
+took counts it, so the next run learns from the last.
+
+Read more: [Vision](https://andrewngo-ini.github.io/mnemoth/vision.html).
+
+# Quick start
+
+Python 3.11 or newer, nothing else:
+
+```sh
+pip install memoose            # or: pipx install memoose, or uvx memoose --help
+```
+
+Store a fact, ask a question, look at the graph:
+
+```sh
+memoose remember "Bao:Person --owns--> auth-service:System" -e "user said 2026-09-18"
+memoose remember "auth-service --uses--> PostgreSQL:Technology" -e "repo://src/db.py#L1-L20"
+memoose recall "who owns auth and what does it run on"
+memoose view                   # the graph in your browser, nothing uploaded
+```
+
+A fact is `source[:Type] --relation--> target[:Type]`. Give the `:Type` the first time an entity
+appears; after that the name is enough. Every fact takes `-e/--evidence`, `--valid-from` and
+`--desc`. Later:
+
+```sh
+memoose maintain               # one worklist: conflicts, duplicates, sessions to distil
+memoose history auth-service   # every change to an entity or fact, by whom and why
+```
+
+Memory lives in `~/.memoose/<dataset>.sqlite`: one dataset per project plus a `user` dataset for
+facts that hold everywhere. `MEMOOSE_DATA_DIR` moves it. Full command table under [CLI](#cli).
+
+# Give your agent memory
+
+The CLI is enough for an agent with a shell. To add the skills, and on Claude Code the hooks and the
+`memory-keeper` subagent:
+
+```sh
+memoose install claude         # or: codex | opencode | cursor
+memoose status                 # what is installed where
+```
+
+`install` copies the skills into the host. On Claude Code it also registers the hooks in
+`~/.claude/settings.json` and drops the agent into `~/.claude/agents/`. It is user-scoped;
+`--project .` scopes it to one repository; `uninstall <host>` reverses it. No MCP server is wired
+unless the agent has no shell: `install <host> --mcp` adds `uvx memoose serve`, which needs
+[uv](https://docs.astral.sh/uv/).
+
+On **Claude Code** the plugin is the simplest route and keeps one copy of everything:
+
+```
+/plugin marketplace add AndrewNgo-ini/mnemoth
+/plugin install memoose@memoose
+```
+
+<details>
+<summary><b>Working from a checkout</b></summary>
+<br>
+
+```sh
+git clone https://github.com/AndrewNgo-ini/mnemoth.git && cd mnemoth && uv sync
+uv run memoose install claude          # skills, hooks and agent from this checkout
+claude --plugin-dir .                  # or load the checkout as a plugin
+uv sync --extra fastembed              # local embeddings (a keyless hash fallback is used otherwise)
+uv sync --extra ontology               # full RDF parsing
+uv run pytest
+```
+
+</details>
+
+> Upgrading from mnemoth: `MNEMOTH_*` variables are still read, an existing `~/.mnemoth` store is
+> reused, and `install` clears the old MCP entry.
+
+**Onboarding.** Ask your agent to onboard Memoose. The
+[`memoose-onboard`](./harness/skills/memoose-onboard/SKILL.md) skill checks what works on this host,
+installs what is missing, then fills the project's memory from its README, docs and git log so the
+next session starts with context.
+
+# How Memoose works
+
+Two layers. A deterministic **engine**: a knowledge graph behind a CLI and 26 MCP tools, no model.
+A **harness** of skills, hooks and a subagent that carries the judgment, run by the model your host
+already has.
+
+- [Overview](https://andrewngo-ini.github.io/mnemoth/) explains the split.
+- [Automatic memory](https://andrewngo-ini.github.io/mnemoth/automatic.html): what runs without being asked, on which hosts.
+- [Evidence & history](https://andrewngo-ini.github.io/mnemoth/trust.html): what a fact carries and how it changes.
+- [Configuration](https://andrewngo-ini.github.io/mnemoth/configuration.html): the switches.
+
+# Usage
+
+### Tools
+
+26 MCP tools; every capability is a tool call on any MCP host.
+
+| area     | tools |
+| -------- | ----- |
+| ontology | `describe_ontology`, `add_entity_type`, `import_ontology` (OWL/RDF/Turtle), `declare_functional_relations` |
+| write    | `remember`, `mark_contradiction`, `supersede`, `merge_entities`, `cross_connect`, `set_bucket_summary`, `forget` |
+| read     | `recall`, `guidance`, `contradiction_candidates`, `history`, `memify_candidates`, `global_context`, `list_datasets` |
+| sessions | `session_start`, `session_add_turn`, `session_set_context`, `session_get`, `session_timeline`, `publish_lessons`, `session_end` |
+
+### Skills
+
+| skill | teaches the host model |
+| ----- | ---------------------- |
+| [`memoose`](./harness/skills/memoose/SKILL.md) | when to recall; how to extract facts with evidence, store procedures, shape the ontology |
+| [`memoose-sessions`](./harness/skills/memoose-sessions/SKILL.md) | the working loop: position and guidance, context sections, outcome, distilling lessons |
+| [`memoose-upkeep`](./harness/skills/memoose-upkeep/SKILL.md) | judging what the store surfaces: contradictions, duplicates, connections, stale summaries |
+| [`memoose-onboard`](./harness/skills/memoose-onboard/SKILL.md) | check what works, install what is missing, then fill this project's memory from its docs and history |
+
+### CLI
+
+Memory operations, the same ones the tools expose:
+
+| command | what it does |
+| ------- | ------------ |
+| `memoose recall "who owns billing"` | search memory; `--mode`, `--limit`, `--superseded`, `--json` |
+| `memoose remember "bao:Person --owns--> auth:System"` | store a fact; `--desc`, `-e`, `--valid-from`; `--when`, `--do`, `--avoid` on a transition; `--stdin` for a JSON batch |
+| `memoose guidance "run the test suite"` | what comes next from a procedure: transitions two hops out, with how past runs ended |
+| `memoose history auth-service` | the provenance ledger for an entity or fact |
+| `memoose contradictions [names]` | hotspots and open contradictions to judge |
+| `memoose ontology` · `memoose datasets` · `memoose context` | entity types and stats · memory scopes · global context |
+| `memoose session start\|turn\|context\|get\|timeline\|lessons\|end` | session lifecycle; `turn --at <procedure>` declares position, `end --outcome` records how it went |
+| `memoose maintain` | the periodic pass: everything that needs judging, in one worklist |
+| `memoose dismiss <key> --reason "..."` | decline a candidate so it is not proposed again |
+| `memoose view` | the graph in your browser as one HTML file (`--superseded` draws history dashed) |
+| `memoose forget --entity X` | delete an entity, fact, session or dataset |
+| `memoose tool <name> --stdin` | any remaining tool, arguments as JSON on stdin |
+
+Output is compact text; over `--max-inline` (2000 chars) it goes to a file whose path is printed.
+`--json` gives the exact tool payload, never cut. Setup:
+
+| command | what it does |
+| ------- | ------------ |
+| `memoose install <host>` | skills, hooks and the agent into a host (`--project`, `--mcp`) |
+| `memoose uninstall <host>` | reverse it |
+| `memoose status` | what is installed where |
+| `memoose serve` | the stdio MCP server, for a host that launches one |
+
+# Benchmarks
+
+Memoose has no model of its own, so its score is inseparable from the model driving it. We report
+the number that matches how it is meant to run: a small, fast model throughout.
+
+LoCoMo is the standard conversational-memory benchmark: long multi-session conversations, then
+questions about them. One model answers from what the memory system retrieves; another grades. We
+run mem0's protocol with their prompts verbatim, so the memory system is the only difference.
+
+### Our run
+
+**Claude Haiku 4.5** as answerer and judge, all 1,540 questions: **90.4% correct** at **4,699 mean
+prompt tokens** ($88.55, September 2026). A reference point, not a competitive entry.
+
+| category    | questions | score |
+| ----------- | --------- | ----- |
+| single-hop  | 841       | 93.5  |
+| temporal    | 321       | 89.7  |
+| multi-hop   | 282       | 88.7  |
+| open-domain | 96        | 70.8  |
+
+Open-domain is the weak category: its gold answers are single turns that never reach the retrieved
+context.
+
+### What others report
+
+Every figure is **self-reported by its vendor** on a different model, judge and retrieval setup.
+They are not comparable with each other or with ours; they are context.
+
+| system                  | reported    | notes |
+| ----------------------- | ----------- | ----- |
+| ZeroMemory              | 96.1        | unverified |
+| Zep                     | 94.7        | third-party testing found 75.1 |
+| ByteRover               | 92.2 / 96.1 | two conflicting figures published |
+| mem0                    | 92.5        | single-hop 94.6, multi-hop 95.4, temporal 92.5, open-domain 82.3; 6,956 prompt tokens |
+| **Memoose (Haiku 4.5)** | **90.4**    | the run above; per-category scores, CI, cost and raw rows published |
+| Dakera                  | 88.2        | no LLM reranking |
+| full context, no memory | ~73         | the whole conversation in the prompt |
+
+mem0 is the only entry with a per-category breakdown; we trail it everywhere, most on multi-hop
+(−6.7) and open-domain (−11.5), at a third fewer prompt tokens with a much smaller answerer.
+Swapping the answerer moves a score more than swapping the memory system, so treat the ordering as
+noise.
+
+Two findings cut against us and are published anyway: the knowledge graph does **not** beat plain
+chunk retrieval on LoCoMo (paired McNemar p = 1.00) and costs 77% more tokens, and a larger
+retrieval budget does not lift the score. LoCoMo asks needle questions over conversations that fit
+in a context window; it does not test what a graph is for.
+
+Protocol, full tables and raw rows: [`benchmarks/`](./benchmarks/README.md). Setup and traps:
+[`benchmarks/SETUP.md`](./benchmarks/SETUP.md).
+
+# Learn more
+
+### Documentation
+
+[Site](https://andrewngo-ini.github.io/mnemoth/)
+
+### Inspiration
+
+- [**cognee**](https://github.com/topoteretes/cognee) for the memory philosophy: a typed graph,
+  ontology-constrained extraction, deterministic ids, hybrid retrieval, contradictions and
+  supersession as first-class concepts. Where cognee calls a model, Memoose has a skill.
+- [**OpenWiki**](https://github.com/langchain-ai/openwiki) for grounded claims: every fact carries a
+  checkable evidence pointer.
+- [**mem0**](https://github.com/mem0ai/mem0) for the LoCoMo protocol, with prompts vendored verbatim
+  from [memory-benchmarks](https://github.com/mem0ai/memory-benchmarks).
+
+### Contributing
+
+Pull requests and [issues](https://github.com/AndrewNgo-ini/mnemoth/issues) are welcome; open an
+issue first for larger changes. `uv run pytest` runs the suite.
+
+### License
+
+Apache 2.0. See [LICENSE](./LICENSE).