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 rea