memU README

The project's README from github.com/NevaMind-AI/memU. As one markdown file: README.md.

memU Banner

memU

Personal memory, stored as Wiki

Across Sessions. Across Agents. Across Devices.

PyPI version License: Apache 2.0 Python 3.11+ Discord Twitter

NevaMind-AI%2FmemU | Trendshift


memU is a lightweight, agent-driven memory system that gives users a shared LLM wiki across sessions, agents, and devices. It automatically distills your own reusable skills from your agent history. Its core memory logic is only 500 lines — compact enough to inspect, understand, and adapt.

Quick start

memU works with Codex, Claude Code, Cursor, OpenClaw, Hermes, WorkBuddy, Cola, pi, and more. See Host adapters.

Cross-device · Free · Unlimited · View online

Get your API key from memu.so, then send this message to your agent:

Read https://memu.pro/SKILL.md, follow its instructions to install and configure memU, API Key is memu_•••••••••(get Api Key from memu.so).

Agent support

This matrix lists the currently tested memU integrations by operating system.

macOS

Agent Mode Memorize Retrieve User note
ChatGPT ChatGPT(Work mode), codex and VS Code extension ✅ ✅
ChatGPT Chat ❌ ❌ Chat mode is not currently supported. Please use Work mode.
Claude Code Desktop and CLI ✅ ✅ If the selected model declines the setup steps, retry with Opus or another model. Sonnet 5 can occasionally do this.
Claude Chat and Cowork ❌ ❌
Cursor — ✅ ✅
OpenClaw — ✅ ✅ Retrieve support has not yet been verified.
Hermes Agent — ✅ ✅
WorkBuddy — ✅ ✅

Windows

Agent Mode Memorize Retrieve User note
ChatGPT ChatGPT(Work mode), codex and VS Code extension ✅ ✅
ChatGPT Chat ❌ ❌ Chat mode is not currently supported. Please use Work mode.
Claude Code Desktop and CLI ✅ ✅ If the selected model declines the setup steps, retry with Opus or another model. Sonnet 5 can occasionally do this.
Claude Chat and Cowork ❌ ❌
Cursor — ✅ ✅
OpenClaw — ✅ ✅
Hermes Agent — ✅ ⚠️ Use a memU version with Windows HERMES_HOME support; older versions may retrieve from the wrong files.
WorkBuddy — ✅ ✅ With Hy3, retrieval may fail. Retry with another model if this happens.

Linux

Agent Mode Memorize Retrieve User note
Codex VS Code extension ❌ ✅
Claude Code CLI ✅ ✅
OpenClaw 4.23 / 7.1 ✅ ✅

Support status reflects the current release and may change as host integrations evolve.

How it works

memU memory system architecture

Automatic skill extraction

Once the scheduled bridging task is installed, memU can turn useful agent history into reusable Markdown skills automatically.

How memU turns agent history into reusable skills

  1. Capture new sessions. The host adapter reads new session history, including messages and tool calls.
  2. Prepare self-evolve jobs. prepare slices each session into a self-contained job with the paths and context the agent needs.
  3. Let the agent decide. The agent reads related existing skills, then chooses to do nothing, patch an existing skill, or create a new one.
  4. Write readable skill Markdown. Each skill has a name, description, and reusable workflow, including useful branches, edge cases, and pitfalls.
  5. Commit and index. commit submits changed skill files through commit_results; memU embeds the skill name and description and stores it under the skill track.
  6. Retrieve it later. On a similar future task, memU returns the relevant skill so any connected agent can use the learned workflow.

The judgment and synthesis stay inside the agent. MemoryService makes no LLM or chat calls; it stores, embeds, and retrieves the skill Markdown the agent prepared.

Self-hosted

Private · Single-device · Embedding key required

To run memU locally with your own storage and embedding provider, send this message to your agent:

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

Uninstall

To uninstall memU, send this message to your agent:

Read https://memu.pro/SKILL.md and follow its instructions to uninstall memU.

By default, uninstalling removes the host integration and tooling while keeping your memory store and ~/.memu/config.env, so a later reinstall can resume where you left off. Memory is erased only when you explicitly ask for it.

Host adapters: memory for desktop coding agents

memU runs as a sidecar to a desktop agent, one binary per host. Each binds two seams:

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>/agent/openclaw-agent.sqlite (SQLite, read-only) + legacy <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/SOUL.md
Cola memu-cola ~/.cola/sessions/<scope>/<session>.jsonl ~/.cola/memory-bank/MEMORY.md
pi memu-pi ~/.pi/agent/sessions/<encoded-cwd>/<session>.jsonl ~/.pi/agent/AGENTS.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 configured memory backend via ~/.memu/config.env — local or MemU Cloud. What one host's sessions taught memU, another host retrieves.

Installation is the one-message setup in Quick start or Self-hosted. 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 memory backend, 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, selected mode, 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.

Developer integration

Applications that already own their conversation history can use memu memorize to prepare self-evolve jobs from 1–10 completed sessions for one external agent and commit the resulting memory, skill, and resource changes. See Developer integration for the canonical input contract and the complete prepare → agent → commit workflow.

CLI

With memU Cloud, sign in at memu.so to view your memory files. With a local installation, memory lives in the shared store configured by MEMU_DB in ~/.memu/config.env — typically ~/.memu/memu.sqlite3 for local SQLite, or a Postgres DSN.

Once installed, your agent retrieves relevant memory automatically before answering. To retrieve manually, run the adapter for your host:

memu-codex retrieve "What should I remember about this project?"
# or: memu-claude-code / memu-cursor / memu-openclaw / memu-hermes / memu-workbuddy / memu-cola / memu-pi / memu-agent

Install or invoke the CLI directly:

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. memU supports Local and Cloud memory backends, selected by MEMU_MEMORY_MODE; an unset mode remains Local for backward compatibility.

For Local / self-hosted installations, 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

Run <binary> doctor to display the resolved mode and verify the same retrieval path the host uses.

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"}},
)

License

Apache-2.0

Partnership Community: LINUX DO

memU (NevaMind-AI/memU)

loop-engineering
Searching Database…

14.6K ·GitHub
What is this?memU is a lightweight, agent-driven memory system that gives coding agents a shared LLM wiki across sessions, agents, and devices, automatically turning your agent history into reusable skills.
Is this a standalone app or does it plug into my existing agent?It runs as a sidecar to a desktop coding agent, with one dedicated binary per host (Codex, Claude Code, Cursor, etc.), rather than being a standalone application.
How do I get it running?Grab an API key from memu.so, then send a one-line message to your agent telling it to read memU's docs and follow the instructions to install and configure it; a separate self-hosted flow exists if you want local storage instead.
Which coding agents does it support?It has tested adapters for Codex, Claude Code, Cursor, OpenClaw, Hermes Agent, WorkBuddy, Cola, and pi, plus a generic detect mode for other agents.
Does memory/retrieval work the same on every agent and OS?No, support varies by host and OS: ChatGPT's Chat mode is unsupported (Work mode only), Claude/Cowork chat isn't supported at all, and some combos like Hermes Agent on Windows or WorkBuddy under Hy3 have known retrieval caveats.
Can I keep my memory fully private and local instead of using memU Cloud?Yes, the self-hosted mode stores memory locally on a single device using your own embedding provider key, instead of syncing through memU Cloud.
What happens to my memory if I uninstall memU?Uninstalling removes the host integration and tooling but keeps your memory store and config file by default, so a later reinstall can resume where you left off; data is only erased if you explicitly ask for it.
How does the automatic skill extraction actually work?A scheduled background task slices new session logs into self-contained jobs, the agent itself decides whether to do nothing, patch, or create a skill, and memU embeds and stores the resulting Markdown skill for retrieval on similar future tasks.
Where does my memory data get stored?By default it lives in a local SQLite file at ~/.memu/memu.sqlite3, but you can point it at a Postgres database (with pgvector) for concurrent access or larger stores.
How complex is the core memory engine?The author kept memU's core memory logic to about 500 lines of code, small enough to read, understand, and modify yourself.
Size
105.5 MB
Stars
14.6K
Age
1y
Commits · 90 Days