memu-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{memu_cli-0.4.0 → memu_cli-0.5.0}/INSTALL-LATEST.md

@@ -121,7 +121,7 @@ Then print your host's packaged guide and follow it to the letter:
 memu-<your-host> docs install
 ```
 
-It walks you through configuring the store in `~/.memu/config.env`, registering
+It walks you through selecting the local or cloud backend in `~/.memu/config.env`, registering
 the scheduled bridging task, and patching your instruction file, each behind a
 verify gate.
 

{memu_cli-0.4.0 → memu_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memu-cli
-Version: 0.4.0
+Version: 0.5.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -32,7 +32,7 @@ Project-URL: Homepage, https://github.com/NevaMind-AI/MemU
 
 # memU
 
-### Personal memory, stored as files
+### Personal memory, stored as Wiki
 
 **Across Sessions. Across Agents. Across Devices.**
 
@@ -48,90 +48,44 @@ Project-URL: Homepage, https://github.com/NevaMind-AI/MemU
 
 ---
 
-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`](src/memu/app/agentic.py) + [`service.py`](src/memu/app/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](#host-adapters-memory-for-desktop-coding-agents).
-
-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.
+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
 
-```python
-from memu.app import MemoryService
+memU works with Codex, Claude Code, Cursor, OpenClaw, Hermes, WorkBuddy, and more. See [Host adapters](#host-adapters-memory-for-desktop-coding-agents).
 
-service = MemoryService(
-    database_config={"metadata_store": {"provider": "sqlite", "dsn": "sqlite:///memu.sqlite3"}},
-)
+Choose Cloud or Local, then send the corresponding message to your agent.
 
-# 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"}],
-)
+### Cloud (coming soon)
 
-# 2. See what is stored, across every track
-files = await service.list_all_recall_files()
+**Cross-device · Free · Unlimited · [View online](https://memu.so)**
 
-# 3. Single-shot embedding retrieval over segments / files / resources
-context = await service.progressive_retrieve("What should I know about this user's launch preferences?")
-```
+> Read [https://memu.pro/SKILL.md](https://memu.pro/SKILL.md) and follow it to install memU.
 
-Or straight from the terminal — no code:
+### Local / self-hosted
 
-```bash
-export OPENAI_API_KEY=sk-...    # embedding API key — the only model calls memU makes
+**Private · Single-device · Embedding key required**
 
-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.
+> Read [https://raw.githubusercontent.com/NevaMind-AI/MemU/main/SKILL.md](https://raw.githubusercontent.com/NevaMind-AI/MemU/main/SKILL.md) and follow it to install memU.
 
 ## How it works
 
 ![memU memory system architecture](assets/structure-v2.png)
 
-### 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.
+## Automatic skill extraction
 
-### Retrieval
+Once the scheduled bridging task is installed, memU can turn useful agent history into reusable Markdown skills automatically.
 
-`progressive_retrieve(query)` embeds the query **once** and returns three ranked layers:
+![How memU turns agent history into reusable skills](assets/skill-extraction.png)
 
-- `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
+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.
 
-There is no intention routing, sufficiency checking, or summarization — one embedding call in, ranked context out.
+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.
 
 ## Host adapters: memory for desktop coding agents
 
@@ -152,15 +106,28 @@ memU runs as a sidecar to a desktop agent (ADR 0008/0009/0010), one binary per h
 
 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.
+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 at the top of this README. [SKILL.md](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.
+
+## CLI
 
-Installation is the one-message setup at the top of this README. [SKILL.md](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.
+With memU Cloud, sign in at [memu.so](https://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.
 
-Afterwards `<binary> doctor` proves the whole loop resolves: config, store, and a live retrieval.
+Once installed, your agent retrieves relevant memory automatically before answering. To retrieve manually, run the adapter for your host:
 
-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).
+```bash
+memu-codex retrieve "What should I remember about this project?"
+# or: memu-claude-code / memu-cursor / memu-openclaw / memu-hermes / memu-workbuddy / memu-agent
+```
 
-## Installation
+Install or invoke the CLI directly:
 
 ```bash
 pip install memu-cli         # library + memu + memu-codex CLIs
@@ -170,7 +137,11 @@ 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:
+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 |
 |---|---|---|
@@ -180,6 +151,9 @@ Values resolve in order: process env → `~/.memu/config.env` → default. Every
 | 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 |
@@ -194,38 +168,6 @@ service = MemoryService(
     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:
-
-```python
-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:
-
-```python
-from pydantic import BaseModel
-
-class TeamScope(BaseModel):
-    team_id: str | None = None
-    user_id: str | None = None
-
-service = MemoryService(user_config={"model": TeamScope})
-```
-
-## Development
-
-```bash
-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/`](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

memu_cli-0.5.0/README.md

@@ -0,0 +1,145 @@
+![memU Banner](assets/banner.png)
+
+<div align="center">
+
+# memU
+
+### Personal memory, stored as Wiki
+
+**Across Sessions. Across Agents. Across Devices.**
+
+[![PyPI version](https://badge.fury.io/py/memu-cli.svg)](https://badge.fury.io/py/memu-cli)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/hQZntfGsbJ)
+[![Twitter](https://img.shields.io/badge/Twitter-Follow-1DA1F2?logo=x&logoColor=white)](https://x.com/memU_ai)
+
+<a href="https://trendshift.io/repositories/17374" target="_blank"><img src="https://trendshift.io/api/badge/repositories/17374" alt="NevaMind-AI%2FmemU | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+
+</div>
+
+---
+
+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, and more. See [Host adapters](#host-adapters-memory-for-desktop-coding-agents).
+
+Choose Cloud or Local, then send the corresponding message to your agent.
+
+### Cloud (coming soon)
+
+**Cross-device · Free · Unlimited · [View online](https://memu.so)**
+
+> Read [https://memu.pro/SKILL.md](https://memu.pro/SKILL.md) and follow it to install memU.
+
+### Local / self-hosted
+
+**Private · Single-device · Embedding key required**
+
+> Read [https://raw.githubusercontent.com/NevaMind-AI/MemU/main/SKILL.md](https://raw.githubusercontent.com/NevaMind-AI/MemU/main/SKILL.md) and follow it to install memU.
+
+## How it works
+
+![memU memory system architecture](assets/structure-v2.png)
+
+## 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](assets/skill-extraction.png)
+
+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.
+
+## 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 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 at the top of this README. [SKILL.md](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.
+
+## CLI
+
+With memU Cloud, sign in at [memu.so](https://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:
+
+```bash
+memu-codex retrieve "What should I remember about this project?"
+# or: memu-claude-code / memu-cursor / memu-openclaw / memu-hermes / memu-workbuddy / memu-agent
+```
+
+Install or invoke the CLI directly:
+
+```bash
+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]"`) |
+
+```python
+service = MemoryService(
+    database_config={"metadata_store": {"provider": "postgres", "dsn": "postgresql://..."}},
+    embedding_profiles={"default": {"provider": "jina"}},
+)
+```
+## License
+
+Apache-2.0

{memu_cli-0.4.0 → memu_cli-0.5.0}/SKILL.md

@@ -62,16 +62,15 @@ binary if your host turns out to have one.
 ```
 
 Read what it prints, top to bottom, and follow it exactly. Every guide has the
-same shape — configure the store once in `~/.memu/config.env`, register the
+same shape — select the local or cloud backend once in `~/.memu/config.env`, register the
 scheduled bridging task (record), patch your instruction file (inject) — and
 every part ends with a **verify gate**; do not proceed past a failing one.
 
 Two rules that hold for every host:
 
-- **One store.** If `~/.memu/config.env` already exists (another agent on this
-  machine is already integrated), reuse it as is. A second store would split
-  the embedding space and both installs would silently retrieve nothing from
-  each other.
+- **One backend.** If `~/.memu/config.env` already exists (another agent on this
+  machine is already integrated), reuse it as is. A second mode or local store
+  would split record and retrieval so the two installs no longer share memory.
 - **Report the outcome.** When done, tell the user which seams are now active —
   memorization, retrieval, or both — and where (the session log being mined,
   the instruction file patched). For `memu-agent`, the detect report decides

memu_cli-0.5.0/docs/adr/0012-cloud-backed-agentic-backend.md

@@ -0,0 +1,108 @@
+ADR 0012: Cloud-Backed Memory Behind the Existing CLI
+
+- Status: Accepted
+- Date: 2026-07-24
+- Builds on: ADR 0008 (two host seams), ADR 0009 (one CLI/config surface)
+- Scope: selecting local or hosted execution for the three agentic memory
+  operations. It does not change `MemoryService`, storage repositories, or the
+  host command surface.
+
+## Context
+
+Every `memu` and `memu-<host>` operation currently constructs a local
+`MemoryService`. That requires a local database plus an embedding provider even
+when the hosted memU service already exposes the same three operations over its
+API-key-authenticated v4 API.
+
+Creating separate cloud binaries would duplicate every host command, retrieval
+instruction, scheduled task, and installation path. Adding HTTP behavior to
+`MemoryService` would instead turn the local composition root into two unrelated
+runtime roles and weaken its embedding-only, storage-pluggable boundary.
+
+## Decision
+
+### One structural capability boundary
+
+`AgenticMemoryBackend` is a structural protocol containing exactly
+`list_all_recall_files`, `progressive_retrieve`, and `commit_results`.
+`MemoryService` already satisfies it and remains the local in-process
+implementation. `CloudMemoryClient` implements it by forwarding requests to:
+
+- `GET /api/v4/memory/`
+- `POST /api/v4/memory/search`
+- `POST /api/v4/memory/`
+
+The cloud client returns successful response dictionaries unchanged. It owns
+Bearer authentication, explicit timeouts, structured cloud errors, and bounded
+retries for transient failures. None of those concerns enter `memu.app`.
+
+### One selector for every caller
+
+`build_agentic_memory_backend_from_env()` is the only backend selector used by
+the main CLI, host retrieval, bridging prepare/commit, and doctor.
+`MEMU_MEMORY_MODE` accepts `local` or `cloud`; absent means `local`, preserving
+existing installs.
+
+Cloud configuration is separate from local embedding configuration:
+
+```env
+MEMU_MEMORY_MODE=cloud
+MEMU_CLOUD_API_KEY=<memu-api-key>
+MEMU_CLOUD_BASE_URL=https://api.memu.so/api/v4/memory/
+```
+
+The base URL has the production value above as its default and remains
+overridable for compatible deployments. Users obtain a memU API key by
+registering at [memu.so](https://memu.so). `MEMU_BASE_URL` and `MEMU_API_KEY`
+keep their existing local-embedding meaning.
+
+The main `memu` CLI retains its local database/embedding flags. They are passed
+as local-mode overrides to the shared selector; cloud mode does not construct a
+local store as a side effect.
+
+### Explicit default owner scope
+
+Cloud requests always send both `user_id` and `agent_id`. Missing, blank, or
+`None` values become the literal `default`. Cloud reads accept only exact
+`user_id` and `agent_id` filters because the public API cannot represent local
+repository operators such as `user_id__in`; unsupported filters fail rather
+than silently widening scope.
+
+### Resource compatibility is visible, not forked
+
+The bridging pipeline remains identical in both modes: it prepares resource
+work and submits `commit_results.resource`. The current cloud API accepts that
+field for wire compatibility but returns an empty `resources` list because it
+does not persist workspace resources yet. Doctor and installation documentation
+state this limitation explicitly; memory and skill recall files are durable.
+
+## Consequences
+
+Positive:
+
+- Existing agent commands, scheduled tasks, and retrieval instructions work in
+  either mode without rewrites.
+- `MemoryService` keeps its three-method public surface and remains free of HTTP
+  and authentication behavior.
+- Cloud credentials cannot be confused with embedding-provider credentials.
+- An old config with no mode keeps its local database and embedding space.
+
+Costs:
+
+- The cloud client has a deliberately narrower `where` vocabulary than a custom
+  local `UserConfig.model`.
+- Resource-description jobs still run in cloud mode even though the service
+  currently does not persist their output. This preserves one bridging
+  pipeline at the cost of temporary redundant work.
+- The project API key may be stored as plaintext in `~/.memu/config.env`; guides
+  require user-only file permissions and process-environment overrides remain
+  available.
+
+## Out of scope
+
+- Dashboard cookie/CSRF APIs
+- OAuth, browser login, or OS keychain integration
+- Local-to-cloud memory migration
+- Cloud resource persistence
+- New CLI binaries
+- Storage protocol, backend, or migration changes

{memu_cli-0.4.0 → memu_cli-0.5.0}/docs/adr/README.md

@@ -11,3 +11,4 @@
 - [0009: Packaging the Codex Integration — pip, a CLI Seam, and One Config Loader](0009-codex-packaging-cli-and-config.md)
 - [0010: Multi-Host Adapters — Claude Code, Cursor, OpenClaw, and Hermes](0010-multi-host-adapters.md)
 - [0011: A Generic Host Adapter — Detect First, Then Bind What Works](0011-generic-host-adapter.md)
+- [0012: Cloud-Backed Memory Behind the Existing CLI](0012-cloud-backed-agentic-backend.md)

{memu_cli-0.4.0 → memu_cli-0.5.0}/npm/README.md

@@ -26,7 +26,16 @@ npx memu-cli list-files
 npx memu-cli retrieve "deploy checklist"
 ```
 
-State persists in a local SQLite database (`./data/memu.sqlite3` by default), so commit in one invocation and retrieve in the next. Every flag has a `MEMU_*` environment variable (`--provider`/`MEMU_EMBED_PROVIDER`, `--embed-model`/`MEMU_EMBED_MODEL`, `--db`/`MEMU_DB`, ...) — run `npx memu-cli <command> --help` for the full list.
+By default, state persists in a local SQLite database
+(`./data/memu.sqlite3`). Set `MEMU_MEMORY_MODE=cloud` and
+`MEMU_CLOUD_API_KEY=<memu-api-key>` to run the same commands through MemU Cloud
+instead. Register at [memu.so](https://memu.so) to obtain a memU API key. The
+production API base defaults to `https://api.memu.so/api/v4/memory/` and can be
+overridden with `MEMU_CLOUD_BASE_URL` for compatible deployments. Local
+embedding settings remain separate (`MEMU_EMBED_PROVIDER`, `MEMU_EMBED_MODEL`,
+`MEMU_DB`, ...). Cloud currently persists memory and skill recall files but not
+submitted workspace resources. Run `npx memu-cli <command> --help` for the
+local-mode flags.
 
 ## Commands
 

{memu_cli-0.4.0 → memu_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "memu-cli"
-version = "0.4.0"
+version = "0.5.0"
 authors = [
     {name = "MemU Team", email = "contact@nevamind.ai"},
 ]

memu_cli-0.5.0/src/memu/agentic_backend.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+
+class AgenticMemoryBackend(Protocol):
+    """The three memory capabilities consumed by CLIs and host adapters.
+
+    ``MemoryService`` satisfies this protocol structurally for local execution.
+    Remote implementations can provide the same surface without adding transport
+    concerns to the local service composition root.
+    """
+
+    async def list_all_recall_files(
+        self,
+        where: dict[str, Any] | None = None,
+    ) -> dict[str, Any]: ...
+
+    async def progressive_retrieve(
+        self,
+        query: str,
+        where: dict[str, Any] | None = None,
+    ) -> dict[str, Any]: ...
+
+    async def commit_results(
+        self,
+        *,
+        recall_files: list[dict[str, Any]] | None = None,
+        resource: list[dict[str, Any]] | None = None,
+        user: dict[str, Any] | None = None,
+    ) -> dict[str, Any]: ...