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/memoose
/plugin install memoose@memoose

git clone https://github.com/AndrewNgo-ini/memoose.git && cd memoose && 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

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.