memU Banner

memU

Personal memory, stored as files

Across Sessions. Across Agents. Across Devices.

PyPI version License: Apache 2.0 Python 3.13+ Discord Twitter

NevaMind-AI%2FmemU | Trendshift

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.

Installation is agent-driven. The guides are written for the agent, not for you. One message is the whole setup — tell your agent:

Read https://raw.githubusercontent.com/NevaMind-AI/MemU/main/SKILL.md and follow it to install memU.

It works for Codex, Claude Code, Cursor, OpenClaw, Hermes, WorkBuddy — and any other agent, via detection. Details in Host adapters.

Want to follow the latest development instead? Install from the newest source (git main) — tell your agent:

Read https://raw.githubusercontent.com/NevaMind-AI/MemU/main/INSTALL-LATEST.md and follow it to install the latest memU.

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

memU memory system architecture

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 adapters: memory for desktop coding agents

memU runs as a sidecar to a desktop agent (ADR 0008/0009/0010), one binary per host. Each 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 instruction file tells the agent to run <binary> retrieve (→ progressive_retrieve) before answering.
Host Binary Session log it mines Instruction file it patches
Codex memu-codex ~/.codex/sessions/**/*.jsonl ~/.codex/AGENTS.md
Claude Code memu-claude-code ~/.claude/projects/<project>/<session>.jsonl ~/.claude/CLAUDE.md
Cursor (Agent/CLI) memu-cursor ~/.cursor/projects/<project>/agent-transcripts/**.jsonl ./AGENTS.md (per project)
OpenClaw memu-openclaw ~/.openclaw/agents/<agentId>/sessions/*.jsonl ~/.openclaw/workspace/AGENTS.md
Hermes Agent memu-hermes ~/.hermes/state.db (SQLite, read-only) ~/.hermes/SOUL.md
WorkBuddy memu-workbuddy ~/.workbuddy/projects/<project>/<session>.jsonl ~/.workbuddy/MEMORY.md
any other agent memu-agent found by memu-agent detect (JSONL dialect sniffed) found by detect (AGENTS.md / CLAUDE.md / SOUL.md / …)

For agents without a dedicated binary, memu-agent detect probes the machine and reports per agent whether memorization works (a recognizable session log exists) and whether retrieval works (an instruction file exists to patch) — then the same verbs run against what it found.

All hosts share one store and one embedding space via ~/.memu/config.env — what one host's sessions taught memU, another host retrieves.

Installation is the one-message setup at the top of this README. SKILL.md is the routing skill it hands your agent: install the package, identify which host you are (falling back to memu-agent detect for anything without a dedicated adapter), print that host's packaged install guide (<binary> docs install), and follow it — configure the store, register the scheduled bridging task, patch the instruction file, each step behind a verify gate — then report which seams (memorization / retrieval) are now active.

Afterwards <binary> 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 HostSpec-sized CLI — the pipeline, verbs, and instruction text are shared (ADR 0010).

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

Project links

Data verified by PyPI on Jul 23, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.10.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Sai1202 from gravatar.com Sai1202

Credits

Author: MemU Team

GitHub Statistics

Data verified by PyPI on Jul 23, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.13

Provides Extra

postgres

Tags

agent agentic agent-harness harness loop-engineering context-engineering context-window memory personal-information workspace retrieval llm

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

memu_cli-0.4.0.tar.gz (10.4 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

memu_cli-0.4.0-cp313-abi3-win_amd64.whl (296.4 kB view details)

Uploaded CPython 3.13+Windows x86-64

memu_cli-0.4.0-cp313-abi3-manylinux_2_39_x86_64.whl (427.7 kB view details)

Uploaded CPython 3.13+manylinux: glibc 2.39+ x86-64

memu_cli-0.4.0-cp313-abi3-manylinux_2_39_aarch64.whl (421.1 kB view details)

Uploaded CPython 3.13+manylinux: glibc 2.39+ ARM64

memu_cli-0.4.0-cp313-abi3-macosx_11_0_arm64.whl (396.5 kB view details)

Uploaded CPython 3.13+macOS 11.0+ ARM64

memu_cli-0.4.0-cp313-abi3-macosx_10_12_x86_64.whl (397.7 kB view details)

Uploaded CPython 3.13+macOS 10.12+ x86-64

File details

Details for the file memu_cli-0.4.0.tar.gz.

File metadata

  • Download URL: memu_cli-0.4.0.tar.gz
  • Upload date:
  • Size: 10.4 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for memu_cli-0.4.0.tar.gz
Algorithm Hash digest
SHA256 3482354702fd96cb485e08490d178b0d45f94535829d31a8a8f443146383f4a5
MD5 90db729df47a29ecbbe02ad642510f48
BLAKE2b-256 b6b5e59b060e9d087cba3640d70bd4978430a9535329a736c0d50dbc1d47e46a

See more details on using hashes here.

Provenance

The following attestation bundles were made for memu_cli-0.4.0.tar.gz:

Publisher: publish-memu-cli.yml on NevaMind-AI/memU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file memu_cli-0.4.0-cp313-abi3-win_amd64.whl.

File metadata

  • Download URL: memu_cli-0.4.0-cp313-abi3-win_amd64.whl
  • Upload date:
  • Size: 296.4 kB
  • Tags: CPython 3.13+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for memu_cli-0.4.0-cp313-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 0aa2a542a57ba46b90044f2aa70757410fc7c2f8520ade84792795dd895af529
MD5 5606a42a4425a3dcb27295186975ed10
BLAKE2b-256 3a2daeaced9c1814c55a14c3b9111b8552671400d0fa562bde2b4ae27b4ece8e

See more details on using hashes here.

Provenance

The following attestation bundles were made for memu_cli-0.4.0-cp313-abi3-win_amd64.whl:

Publisher: publish-memu-cli.yml on NevaMind-AI/memU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file memu_cli-0.4.0-cp313-abi3-manylinux_2_39_x86_64.whl.

File metadata

File hashes

Hashes for memu_cli-0.4.0-cp313-abi3-manylinux_2_39_x86_64.whl
Algorithm Hash digest
SHA256 a90d046121bc514b1a630b53522be073c2659675c641d10bfcd000a463115cef
MD5 401beca34e57d1a55dc74484f60e3e06
BLAKE2b-256 3eb9de7a0d9c8abae90ca4138e141c71536bf4203e78d3665539bde01d86a4c3

See more details on using hashes here.

Provenance

The following attestation bundles were made for memu_cli-0.4.0-cp313-abi3-manylinux_2_39_x86_64.whl:

Publisher: publish-memu-cli.yml on NevaMind-AI/memU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file memu_cli-0.4.0-cp313-abi3-manylinux_2_39_aarch64.whl.

File metadata

File hashes

Hashes for memu_cli-0.4.0-cp313-abi3-manylinux_2_39_aarch64.whl
Algorithm Hash digest
SHA256 92f6ae2bade5629e71ee17514972c409f3485250182c757a5a59f35a8220ca3e
MD5 919db2480c11982bcd1fe09e238795b0
BLAKE2b-256 d320e3560f43401bbb8f4dce4c3a81fc15809837cda704cf3bcf43a0b4b4309b

See more details on using hashes here.

Provenance

The following attestation bundles were made for memu_cli-0.4.0-cp313-abi3-manylinux_2_39_aarch64.whl:

Publisher: publish-memu-cli.yml on NevaMind-AI/memU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file memu_cli-0.4.0-cp313-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for memu_cli-0.4.0-cp313-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9cf274b7bc19f198a9de5629f6fdb8fe4e481fae0a749e5a789a573e4f4f01cd
MD5 533c877e0b874aa774bc2500d6d08df5
BLAKE2b-256 5475c38dfc92ebc691845723dabac98f07479b7e315d055a8355af8448b1d291

See more details on using hashes here.

Provenance

The following attestation bundles were made for memu_cli-0.4.0-cp313-abi3-macosx_11_0_arm64.whl:

Publisher: publish-memu-cli.yml on NevaMind-AI/memU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file memu_cli-0.4.0-cp313-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for memu_cli-0.4.0-cp313-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 3ad381e8b2033bc072ee1382c8a3e81efce19c7c8da82faa37fb802d2ea52d4c
MD5 33d4e68c5b2d08dc0aa45e593b6f93d4
BLAKE2b-256 97afba67d9c0e6faa8f4f525ef06d893712333b9b25d5cdaea59445f073e417b

See more details on using hashes here.

Provenance

The following attestation bundles were made for memu_cli-0.4.0-cp313-abi3-macosx_10_12_x86_64.whl:

Publisher: publish-memu-cli.yml on NevaMind-AI/memU

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

Pre-release

0.11.0b3

2 files

Pre-release

0.11.0b2

2 files

Pre-release

0.11.0b1

2 files

0.10.0

2 files

0.9.0

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.0

6 files

This release

0.4.0 This release

6 files

0.3.0

6 files

0.2.0

6 files

0.1.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page