Memoose: A Dual-Path Memory System for Proactive Agents

Contents

• What is Memoose
• Quick start
• Give your agent memory
• How Memoose works
• Usage: tools · skills · CLI
• Benchmarks
• Learn more: documentation · inspiration · contributing · 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: 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.

Quick start

Python 3.11 or newer, nothing else:

pip install memoose            # or: pipx install memoose, or uvx memoose --help

Store a fact, ask a question, look at the graph:

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:

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.

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:

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.

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

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

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 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 explains the split.
• Automatic memory: what runs without being asked, on which hosts.
• Evidence & history: what a fact carries and how it changes.
• Configuration: the switches.

Usage

Tools

26 MCP tools; every capability is a tool call on any MCP host.

Skills

CLI

Memory operations, the same ones the tools expose:

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:

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.

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.

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/. Setup and traps: benchmarks/SETUP.md.

Learn more

Documentation

Site

Inspiration

• 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 for grounded claims: every fact carries a checkable evidence pointer.
• mem0 for the LoCoMo protocol, with prompts vendored verbatim from memory-benchmarks.

Contributing

Pull requests and issues are welcome; open an issue first for larger changes. uv run pytest runs the suite.

License

Apache 2.0. See LICENSE.