memu-cli 0.2.0

CLI distribution channel for memU (same engine as memu-py). Personal memory as files.

memU

Personal memory, stored as files

Across Agents. Fast retrieval. Lower cost.

---

memU is a 500-line memory system for AI agents. Agents write what's worth keeping as Markdown; memU stores it, embeds it, and retrieves ranked context in a single call — embeddings are the only model calls it makes. The entire memory logic lives in agentic.py + service.py; everything else is pluggable storage and embedding transport.

Quick start

from memu.app import MemoryService

service = MemoryService(
    database_config={"metadata_store": {"provider": "sqlite", "dsn": "sqlite:///memu.sqlite3"}},
)

# 1. Persist agent-prepared memory: recall files (memory/skill tracks) + resources
await service.commit_results(
    recall_files=[
        {
            "name": "Profile",
            "track": "memory",
            "description": "who the user is",
            "content": "# Profile\n- prefers dark roast coffee\n- ships on Fridays",
        },
        {
            "name": "deploy-checklist",
            "track": "skill",
            "description": "how to deploy this repo",
            "content": "1. run tests\n2. tag\n3. push",
        },
    ],
    resource=[{"path": "/abs/path/notes.md", "description": "meeting notes from the launch review"}],
)

# 2. See what is stored, across every track
files = await service.list_all_recall_files()

# 3. Single-shot embedding retrieval over segments / files / resources
context = await service.progressive_retrieve("What should I know about this user's launch preferences?")

Or straight from the terminal — no code:

export OPENAI_API_KEY=sk-...    # embedding API key — the only model calls memU makes

npx memu-cli commit results.json     # {"recall_files": [...], "resource": [...]}
npx memu-cli list-files
npx memu-cli retrieve "What should I know about this user's launch preferences?"

State persists in a local SQLite database (./data/memu.sqlite3 by default), so commit in one invocation and retrieve in the next.

How it works

The data model

Memory is a set of recall files — one Markdown document per topic (track="memory") or per learned skill (track="skill"). Committing a file also writes its search index:

Record	What it is	How it's embedded
RecallFile	The Markdown document itself (name, track, description, content)	name: description, once at creation
RecallFileSegment	Searchable slices of a file	memory track: one per content line (headings skipped); skill track: one name: description segment per skill
Resource	A raw source on disk (url, caption)	its one-line caption

Segments are reconciled on every commit: lines that disappeared are deleted, only genuinely new lines are embedded, unchanged lines keep their vectors — so re-committing a lightly edited file is nearly free.

Retrieval

progressive_retrieve(query) embeds the query once and returns three ranked layers:

• segments — the matched slices, narrowest and usually most on-point, each with a score
• files — the documents those segments belong to (usually what you want), each scored by its best segment and carrying its linked resource_urls
• resources — matching raw sources, for when summaries are not enough

There is no intention routing, sufficiency checking, or summarization — one embedding call in, ranked context out.

Host adapter: memory for desktop coding agents

memu-codex runs memU as a sidecar to Codex-style agents (ADR 0008/0009). It binds two seams:

• record — a scheduled bridging task slices new session logs into self-contained job files; the agent itself distills them into memory/skill Markdown; commit submits whatever the agent left on disk back through commit_results.
• inject — a standing instruction in the host's global instruction file (~/.codex/AGENTS.md) tells the agent to run memu-codex retrieve (→ progressive_retrieve) before answering.

Installation is agent-driven. The install guide is written for the agent, not for you — install the package, then hand the guide to your agent and let it do the rest (configure the store, register the scheduled bridging task, patch the instruction file — each step ends with a verify gate):

pip install memu-cli    # puts memu + memu-codex on PATH

Then tell your agent:

Run memu-codex docs install, read the guide it prints, and follow it to install memU.

Afterwards memu-codex doctor proves the whole loop resolves: config, store, and a live retrieval.

Adding another host means implementing one TranscriptSource (where its session logs live, how its records are shaped) plus a thin CLI — the pipeline and instruction text are shared.

Installation

pip install memu-cli         # library + memu + memu-codex CLIs
npx memu-cli --help          # CLI via npm launcher (engine: PyPI package memu-cli)
uvx --from memu-cli memu     # CLI via uv, no install

Configuration

Values resolve in order: process env → ~/.memu/config.env → default. Every CLI flag has a matching variable:

Setting	Env var	Default
Store	MEMU_DB	./data/memu.sqlite3 (CLI); required for host adapters
Embedding provider	MEMU_EMBED_PROVIDER	openai (also: jina, voyage, doubao, openrouter); legacy MEMU_LLM_PROVIDER still read
API key	MEMU_API_KEY	the provider's env var, e.g. OPENAI_API_KEY
Embedding model	MEMU_EMBED_MODEL	the provider's default
Base URL	MEMU_BASE_URL	the provider's default

Storage backends

Provider	DSN	Vector search	Use for
inmemory	—	brute-force cosine	tests, throwaway sessions
sqlite	sqlite:///path.sqlite3	brute-force cosine	local/default, single writer
postgres	postgresql://...	pgvector	concurrent access, large stores (pip install "memu-cli[postgres]")

service = MemoryService(
    database_config={"metadata_store": {"provider": "postgres", "dsn": "postgresql://..."}},
    embedding_profiles={"default": {"provider": "jina"}},
)

Multi-tenancy

Every record carries optional scope fields (user_id, agent_id by default). Pass user= on writes and where= on reads to partition one store:

await service.commit_results(recall_files=[...], user={"user_id": "alice"})
await service.progressive_retrieve("launch preferences", where={"user_id": "alice"})

Need different scope fields? Supply your own model — filters are validated against it, unknown fields raise:

from pydantic import BaseModel

class TeamScope(BaseModel):
    team_id: str | None = None
    user_id: str | None = None

service = MemoryService(user_config={"model": TeamScope})

Development

make install     # uv sync + pre-commit hooks
make test        # pytest with coverage
make check       # lock check, pre-commit, mypy, deptry

Architecture decisions live in docs/adr/ — notably tracked workspace memorization (ADR 0006), the segment/file/resource retrieval lines (ADR 0007), and the host-adapter seams (ADR 0008/0009).

License

Apache-2.0