memu-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{memu_cli-0.1.0 → memu_cli-0.2.0}/.github/workflows/build.yml

@@ -25,7 +25,7 @@ jobs:
 
       - name: Sync dependencies
         run: |
-          uv sync --frozen --extra document
+          uv sync --frozen
           uv run pre-commit install
 
       - name: Run style checks

memu_cli-0.2.0/.github/workflows/publish-memu-cli.yml

@@ -0,0 +1,167 @@
+# Publishes the engine snapshot to PyPI under the distribution name `memu-cli`.
+#
+# `memu-cli` is the CLI release channel: it ships the same `memu` module and
+# entry points as `memu-py`, but versions independently of the release-please
+# train so the npm launcher and docs can point at a stable install target.
+# The rename happens at build time only — pyproject.toml in the repo always
+# says `memu-py`.
+#
+# First-time setup: add a trusted publisher on PyPI for project `memu-cli`
+# (workflow: publish-memu-cli.yml, environment: pypi).
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "memu-cli version to publish (independent of memu-py, e.g. 0.1.1)"
+        required: true
+        type: string
+
+name: publish-memu-cli
+
+jobs:
+  build-wheels:
+    name: build wheels (${{ matrix.label }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            label: linux-x86_64
+            target: x86_64-unknown-linux-gnu
+            extra-args: "--compatibility manylinux_2_39"
+            python-version: "3.13"
+          - os: ubuntu-latest
+            label: linux-aarch64
+            target: aarch64-unknown-linux-gnu
+            extra-args: "--compatibility manylinux_2_39"
+            python-version: "3.13"
+          - os: macos-15-intel
+            label: macos-x86_64
+            target: ""
+            extra-args: ""
+            python-version: "3.13"
+          - os: macos-latest
+            label: macos-aarch64
+            target: ""
+            extra-args: ""
+            python-version: "3.13"
+          - os: windows-latest
+            label: windows-x86_64
+            target: ""
+            extra-args: ""
+            python-version: "3.13"
+    steps:
+      - uses: actions/checkout@v6
+
+      # No $ anchors: Windows runners check out with CRLF line endings,
+      # where a trailing \r sits between the closing quote and the newline.
+      - name: Rename distribution to memu-cli
+        shell: bash
+        run: |
+          perl -pi -e 's/^name = "memu-py"/name = "memu-cli"/' pyproject.toml
+          perl -pi -e 's/^version = "[^"]*"/version = "${{ inputs.version }}"/ if $. < 10' pyproject.toml
+          perl -pi -e 's/^description = "[^"]*"/description = "CLI distribution channel for memU (same engine as memu-py). Personal memory as files."/' pyproject.toml
+          grep -q '^name = "memu-cli"' pyproject.toml || { echo "::error::rename to memu-cli did not apply"; exit 1; }
+          grep -E '^(name|version|description) = ' pyproject.toml | head -3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install maturin
+        run: uv tool install maturin
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Setup cross-compilation for Linux ARM64
+        if: matrix.label == 'linux-aarch64'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
+
+      - name: Build wheel
+        run: uvx maturin build --release --out dist ${{ matrix.extra-args }} ${{ matrix.target && format('--target {0}', matrix.target) || '' }}
+        env:
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
+
+      - name: Smoke test wheel
+        if: matrix.label != 'linux-aarch64'
+        shell: bash
+        run: uvx --isolated --from ./dist/memu_cli-*.whl memu --help
+
+      - name: Upload wheel artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: memu-cli-wheels-${{ matrix.label }}
+          path: dist/*.whl
+          if-no-files-found: error
+
+  build-sdist:
+    name: build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Rename distribution to memu-cli
+        shell: bash
+        run: |
+          perl -pi -e 's/^name = "memu-py"/name = "memu-cli"/' pyproject.toml
+          perl -pi -e 's/^version = "[^"]*"/version = "${{ inputs.version }}"/ if $. < 10' pyproject.toml
+          perl -pi -e 's/^description = "[^"]*"/description = "CLI distribution channel for memU (same engine as memu-py). Personal memory as files."/' pyproject.toml
+          grep -q '^name = "memu-cli"' pyproject.toml || { echo "::error::rename to memu-cli did not apply"; exit 1; }
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install maturin
+        run: uv tool install maturin
+
+      - name: Build sdist
+        run: uvx maturin sdist --out dist
+
+      - name: Upload sdist artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: memu-cli-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    name: publish memu-cli to PyPI
+    runs-on: ubuntu-latest
+    needs:
+      - build-wheels
+      - build-sdist
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download wheel artifacts
+        uses: actions/download-artifact@v7
+        with:
+          pattern: memu-cli-wheels-*
+          merge-multiple: true
+          path: dist
+
+      - name: Download sdist artifact
+        uses: actions/download-artifact@v7
+        with:
+          name: memu-cli-sdist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true

memu_cli-0.2.0/AGENTS.md

@@ -0,0 +1,77 @@
+# AGENTS.md
+
+Operational guide for AI coding agents working in this repository.
+
+## Mission
+
+Ship small, verified feature and bugfix changes while preserving memU's current architecture.
+
+Core invariants:
+
+- `MemoryService` (`src/memu/app/service.py`) is the composition root: config, storage, and the embedding client pool. Its public surface is exactly the three `AgenticMixin` entry points — `list_all_recall_files`, `progressive_retrieve`, `commit_results`.
+- memU is embedding-only. No LLM/chat call happens anywhere in the service; do not add one.
+- Storage is pluggable across `inmemory`, `sqlite`, and `postgres`; repository contract changes require backend parity.
+- Scope data comes from `UserConfig.model`; validate `where` filters (`_normalize_where`) and do not bypass scope filtering.
+- Retrieval config lives in `ProgressiveRetrieveConfig` (`file` + `resource` layers); embedding profiles in `EmbeddingProfilesConfig`.
+
+## Layer Map
+
+- Service + three entry points: `src/memu/app/service.py`, `src/memu/app/agentic.py`
+- Config models/defaults: `src/memu/app/settings.py`
+- Storage protocols/factory: `src/memu/database/interfaces.py`, `src/memu/database/factory.py`
+- Backends: `src/memu/database/{inmemory,sqlite,postgres}/*`
+- Vector math/ranking: `src/memu/vector.py`
+- Embedding clients: `src/memu/embedding/*`
+- CLI (`memu`): `src/memu/cli.py`; shared `MEMU_*` config: `src/memu/env.py`
+- Host adapters (`memu-codex`, bridging pipeline): `src/memu/hosts/*`
+- Tests: `tests/*`
+
+Read the relevant implementation and nearby tests first. Prefer local patterns over new abstractions.
+
+## Implementation Rules
+
+- Keep changes narrow and localized to the affected layer.
+- Preserve async behavior and result shapes unless the task explicitly asks for a breaking change.
+- Maintain type hints and mypy compatibility.
+- Keep provider-specific logic inside `memu.embedding.backends`; storage-neutral logic outside concrete backends.
+- Do not duplicate client caching — use the existing `ClientPool` pattern.
+- Do not silently swallow errors that should be visible to callers or tests.
+
+## Backend Parity
+
+If a repository method, model field, filter behavior, or vector search contract changes:
+
+1. Update the protocol in `src/memu/database/repositories/`.
+2. Update `inmemory`, `sqlite`, and `postgres` implementations where applicable.
+3. Extend `tests/test_agentic.py` (runs against inmemory + sqlite).
+4. Check migrations/bootstrap behavior for SQL backends (`src/memu/database/postgres/migrations/`).
+
+## Testing And Validation
+
+Use `uv` for local runs.
+
+- Setup: `make install`
+- Run all tests: `make test`
+- Run focused tests: `uv run python -m pytest tests/<target_test>.py`
+- Full quality checks: `make check`
+
+Useful focused areas:
+
+- The three entry points end-to-end: `tests/test_agentic.py`
+- Vector ranking: `tests/test_vector.py`
+- Embedding providers/gateway: `tests/test_embedding.py`
+- CLI surface: `tests/test_cli.py`
+- Host adapter inject seam: `tests/test_host_instruction.py`
+
+## Documentation Rules
+
+- Update `README.md` or `npm/README.md` when user-visible behavior changes.
+- Add or update ADRs under `docs/adr/` for architectural changes; existing ADRs are historical records — do not rewrite them.
+- Do not document speculative features as implemented.
+
+## Done Criteria
+
+- Code compiles for touched paths; tests for changed behavior pass.
+- New behavior has test coverage.
+- Backend parity considered and implemented where needed.
+- No unrelated files modified.

memu_cli-0.2.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: memu-cli
+Version: 0.2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: numpy>=2.3.4
+Requires-Dist: openai>=2.8.0
+Requires-Dist: pydantic>=2.12.4
+Requires-Dist: sqlmodel>=0.0.27
+Requires-Dist: alembic>=1.14.0
+Requires-Dist: pendulum>=3.1.0
+Requires-Dist: pgvector>=0.3.4 ; extra == 'postgres'
+Requires-Dist: sqlalchemy[postgresql-psycopgbinary]>=2.0.36 ; extra == 'postgres'
+Provides-Extra: postgres
+License-File: LICENSE.txt
+Summary: CLI distribution channel for memU (same engine as memu-py). Personal memory as files.
+Keywords: agent,agentic,agent-harness,harness,loop-engineering,context-engineering,context-window,memory,personal-information,workspace,retrieval,llm
+Author-email: MemU Team <contact@nevamind.ai>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Bug Tracker, https://github.com/NevaMind-AI/MemU/issues
+Project-URL: Documentation, https://github.com/NevaMind-AI/MemU#readme
+Project-URL: Homepage, https://github.com/NevaMind-AI/MemU
+
+![MemU Banner](assets/banner.png)
+
+<div align="center">
+
+# memU
+
+### Personal memory, stored as files
+
+**Across Agents. Fast retrieval. Lower cost.**
+
+[![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 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.
+
+## Quick start
+
+```python
+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:
+
+```bash
+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](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.
+
+### 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):
+
+```bash
+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
+
+```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. 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]"`) |
+
+```python
+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:
+
+```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.2.0/README.md

@@ -0,0 +1,187 @@
+![MemU Banner](assets/banner.png)
+
+<div align="center">
+
+# memU
+
+### Personal memory, stored as files
+
+**Across Agents. Fast retrieval. Lower cost.**
+
+[![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 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.
+
+## Quick start
+
+```python
+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:
+
+```bash
+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](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.
+
+### 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):
+
+```bash
+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
+
+```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. 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]"`) |
+
+```python
+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:
+
+```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