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

{memu_cli-0.2.0 → memu_cli-0.3.0}/.github/workflows/publish-memu-cli.yml

@@ -1,10 +1,9 @@
-# Publishes the engine snapshot to PyPI under the distribution name `memu-cli`.
+# Publishes the engine to PyPI as `memu-cli` — the one and only distribution.
 #
-# `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`.
+# `memu-cli` versions independently of the release-please train (which still
+# cuts GitHub releases and the changelog), so the npm launcher and docs can
+# point at a stable install target; the version is set at build time from the
+# workflow input.
 #
 # First-time setup: add a trusted publisher on PyPI for project `memu-cli`
 # (workflow: publish-memu-cli.yml, environment: pypi).
@@ -13,7 +12,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "memu-cli version to publish (independent of memu-py, e.g. 0.1.1)"
+        description: "memu-cli version to publish (e.g. 0.2.1)"
         required: true
         type: string
 
@@ -57,14 +56,12 @@ jobs:
 
       # 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
+      - name: Set memu-cli version
         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
+          grep -q '^name = "memu-cli"' pyproject.toml || { echo "::error::pyproject is not memu-cli"; exit 1; }
+          grep -E '^(name|version) = ' pyproject.toml | head -2
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -108,13 +105,11 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - name: Rename distribution to memu-cli
+      - name: Set memu-cli version
         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 -q '^name = "memu-cli"' pyproject.toml || { echo "::error::pyproject is not memu-cli"; exit 1; }
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7

{memu_cli-0.2.0 → memu_cli-0.3.0}/.github/workflows/release-please.yml

@@ -120,6 +120,9 @@ jobs:
           path: dist/*.tar.gz
           if-no-files-found: error
 
+  # Release artifacts go to the GitHub release only. PyPI publishing happens
+  # exclusively through publish-memu-cli.yml (the `memu-cli` distribution,
+  # versioned independently of this release train).
   publish:
     name: publish release artifacts
     runs-on: ubuntu-latest
@@ -128,9 +131,7 @@ jobs:
       - build-wheels
       - build-sdist
     if: ${{ needs.release-please.outputs.releases_created == 'true' && needs.release-please.outputs.tag_name != '' }}
-    environment: pypi
     permissions:
-      id-token: write
       contents: write
     steps:
       - name: Download wheel artifacts
@@ -153,8 +154,3 @@ jobs:
           file: dist/*
           tag: ${{ needs.release-please.outputs.tag_name }}
           file_glob: true
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          packages-dir: dist/

{memu_cli-0.2.0 → memu_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memu-cli
-Version: 0.2.0
+Version: 0.3.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -17,7 +17,7 @@ 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.
+Summary: Personal memory as files — fast retrieval, higher accuracy, lower cost.
 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
@@ -50,6 +50,12 @@ 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 — and any other agent, via detection. Details in [Host adapters](#host-adapters-memory-for-desktop-coding-agents).
+
 ## Quick start
 
 ```python
@@ -123,26 +129,31 @@ Segments are reconciled on every commit: lines that disappeared are deleted, onl
 
 There is no intention routing, sufficiency checking, or summarization — one embedding call in, ranked context out.
 
-## Host adapter: memory for desktop coding agents
+## Host adapters: memory for desktop coding agents
 
-`memu-codex` runs memU as a sidecar to Codex-style agents (ADR 0008/0009). It binds two seams:
+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 global instruction file (`~/.codex/AGENTS.md`) tells the agent to run `memu-codex retrieve` (→ `progressive_retrieve`) before answering.
+- **inject** — a standing instruction in the host's instruction file tells the agent to run `<binary> 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):
+| 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` |
+| **any other agent** | `memu-agent` | found by `memu-agent detect` (JSONL dialect sniffed) | found by `detect` (AGENTS.md / CLAUDE.md / SOUL.md / …) |
 
-```bash
-pip install memu-cli    # puts memu + memu-codex on PATH
-```
+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.
 
-Then tell your agent:
+All hosts share one store and one embedding space via `~/.memu/config.env` — what one host's sessions taught memU, another host retrieves.
 
-> Run `memu-codex docs install`, read the guide it prints, and follow it to install memU.
+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.
 
-Afterwards `memu-codex doctor` proves the whole loop resolves: config, store, and a live retrieval.
+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 thin CLI — the pipeline and instruction text are shared.
+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
 

{memu_cli-0.2.0 → memu_cli-0.3.0}/README.md

@@ -22,6 +22,12 @@
 
 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 — and any other agent, via detection. Details in [Host adapters](#host-adapters-memory-for-desktop-coding-agents).
+
 ## Quick start
 
 ```python
@@ -95,26 +101,31 @@ Segments are reconciled on every commit: lines that disappeared are deleted, onl
 
 There is no intention routing, sufficiency checking, or summarization — one embedding call in, ranked context out.
 
-## Host adapter: memory for desktop coding agents
+## Host adapters: memory for desktop coding agents
 
-`memu-codex` runs memU as a sidecar to Codex-style agents (ADR 0008/0009). It binds two seams:
+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 global instruction file (`~/.codex/AGENTS.md`) tells the agent to run `memu-codex retrieve` (→ `progressive_retrieve`) before answering.
+- **inject** — a standing instruction in the host's instruction file tells the agent to run `<binary> 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):
+| 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` |
+| **any other agent** | `memu-agent` | found by `memu-agent detect` (JSONL dialect sniffed) | found by `detect` (AGENTS.md / CLAUDE.md / SOUL.md / …) |
 
-```bash
-pip install memu-cli    # puts memu + memu-codex on PATH
-```
+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.
 
-Then tell your agent:
+All hosts share one store and one embedding space via `~/.memu/config.env` — what one host's sessions taught memU, another host retrieves.
 
-> Run `memu-codex docs install`, read the guide it prints, and follow it to install memU.
+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.
 
-Afterwards `memu-codex doctor` proves the whole loop resolves: config, store, and a live retrieval.
+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 thin CLI — the pipeline and instruction text are shared.
+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
 

memu_cli-0.3.0/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: install-memu
+description: Install memU for whatever agent you are — identify your host, print its packaged install guide, and follow it to wire both seams (record and inject). Use when the user asks to install, set up, or integrate memU.
+---
+
+# Install memU
+
+> **Audience: the agent.** A user has pointed you at this file ("read SKILL.md
+> and follow it to install memU"). This skill does not contain the install
+> steps — it routes you to the right guide, which ships inside the memU package
+> and is always in sync with the installed code. Do not install from memory or
+> from blog posts; print the guide and follow it to the letter.
+
+memU integrates with a host agent through two seams: **record** (a scheduled
+bridging task mines your session log into durable memory) and **inject** (a
+standing instruction in your instruction file makes you retrieve before
+answering). Each supported host has its own adapter binary carrying its own
+install guide. Your job here is three steps: install the package, pick your
+binary, print and follow its guide.
+
+## Step 1 — install the package
+
+```
+pip install memu-cli
+```
+
+This puts `memu` and every host-adapter binary on `PATH`. If `pip` is not the
+right tool for this machine (managed Python, uv-only), use the equivalent —
+what matters is that the binaries below resolve from a bare, non-interactive
+shell.
+
+## Step 2 — pick your host binary
+
+Identify **which agent you are** (not which agents are installed — the one
+executing this skill):
+
+| You are | Your binary |
+| --- | --- |
+| Codex | `memu-codex` |
+| Claude Code | `memu-claude-code` |
+| Cursor (Agent/CLI) | `memu-cursor` |
+| OpenClaw | `memu-openclaw` |
+| Hermes Agent | `memu-hermes` |
+| anything else | `memu-agent` |
+
+Unsure, or not in the table? You are `memu-agent`. Run:
+
+```
+memu-agent detect
+```
+
+It probes this machine and reports, per agent, whether **memorization** works
+(a recognizable session log exists) and whether **retrieval** works (an
+instruction file exists to patch) — and it will redirect you to a dedicated
+binary if your host turns out to have one.
+
+## Step 3 — print your guide and follow it
+
+```
+<your-binary> docs install
+```
+
+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
+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.
+- **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
+  this; a retrieval-only integration is a valid outcome to report, not a
+  failure to hide.

{memu_cli-0.2.0 → memu_cli-0.3.0}/docs/adr/0009-codex-packaging-cli-and-config.md

@@ -48,7 +48,7 @@ silently returns nothing.
 
 ### 1. Distribute via pip; do not ship a parallel npm package
 
-memU is installed as a Python package (`pip install memu-py`), exposing two console entrypoints:
+memU is installed as a Python package (`pip install memu-cli`), exposing two console entrypoints:
 `memu` (the library's own surface) and `memu-codex` (the host adapter — see Decision 2). No npm
 package is built for this integration.
 

memu_cli-0.3.0/docs/adr/0010-multi-host-adapters.md

@@ -0,0 +1,167 @@
+ADR 0010: Multi-Host Adapters — Claude Code, Cursor, OpenClaw, and Hermes
+
+- Status: Accepted
+- Date: 2026-07-16
+- Builds on: ADR 0008 (two integration surfaces), ADR 0009 (packaging, CLI seam, one config
+  loader)
+- Scope: adding four host adapters beyond Codex, and the two pieces of shared structure that
+  shipping a second host forced: a common CLI builder, and per-host working trees. It does
+  **not** revisit the pipeline, the seams, or the config decisions of 0008/0009.
+
+## Context
+
+ADR 0009 closed with a claim and an IOU. The claim: "a second host is a `TranscriptSource`
+and a CLI, not a forked pipeline." The IOU: the working directories (`~/.memu/jobs`,
+`~/.memu/sessions`, the touched-file log) are shared and wiped per run — "two hosts' bridging
+tasks running at the same time would race. Fine while Codex is the only host; must be settled
+before the second one ships."
+
+Four hosts now ship at once: **Claude Code**, **Cursor**, **OpenClaw**, and **Hermes Agent**.
+Each was located empirically (inspecting a live machine and, for OpenClaw and Hermes, the
+hosts' own source) rather than from documentation alone:
+
+| Host | Session log | Container | Record shape |
+| --- | --- | --- | --- |
+| Codex | `~/.codex/sessions/**/*.jsonl` | JSONL per session | `{timestamp, payload: {type, role, …}}`; `type: message` (user/assistant) vs `function_call`/`function_call_output` |
+| Claude Code | `~/.claude/projects/<escaped-cwd>/<session-uuid>.jsonl` (subagent transcripts in per-session subdirs) | JSONL per session | `{type: user\|assistant, timestamp, message: {role, content}}`, one content block per record: `text` / `tool_use` / `tool_result` / `thinking`; plus non-message noise types (`queue-operation`, `attachment`, `system`, `pr-link`, `last-prompt`) and `isMeta` user records |
+| Cursor (Agent/CLI) | `~/.cursor/projects/<escaped-cwd>/agent-transcripts/<id>/<id>.jsonl` | JSONL per session | `{role, message: {content: [blocks]}}`; `text` and `tool_use` blocks, often in one record; **no timestamps**. The IDE's Composer chats live in the editor's `state.vscdb` SQLite and are out of scope |
+| OpenClaw | `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl` (`-topic-<threadId>` suffix for topic sessions; `sessions.json` index alongside; root moves with `OPENCLAW_STATE_DIR`) | JSONL per session | parent-linked entry tree: `{type: session\|message\|compaction\|custom…, id, parentId, timestamp, message: {role, content}}`; roles `user`/`assistant`/`toolResult` |
+| Hermes Agent | `~/.hermes/state.db` (moves with `HERMES_HOME`; `~/.hermes/sessions/saved/` holds only manual snapshots) | **SQLite**, WAL mode | `sessions` + `messages` tables; OpenAI-shaped rows: `role` (`system`/`user`/`assistant`/`tool`), `content`, `tool_calls`, `tool_call_id`, epoch-seconds `timestamp` |
+
+And the inject seam's landing file per host:
+
+| Host | Instruction file | Why |
+| --- | --- | --- |
+| Codex | `~/.codex/AGENTS.md` | global, loaded every session (ADR 0009) |
+| Claude Code | `~/.claude/CLAUDE.md` | the global memory file, loaded in every project |
+| Cursor | `./AGENTS.md` (per project) | Cursor's CLI honors no global instruction *file*; User Rules are IDE settings out of a CLI's reach |
+| OpenClaw | `~/.openclaw/workspace/AGENTS.md` | the workspace file loaded at the start of every session |
+| Hermes | `~/.hermes/SOUL.md` | the one file loaded from `HERMES_HOME` regardless of cwd; project files (`.hermes.md`, `AGENTS.md`) would miss sessions started elsewhere |
+
+Two of the four break assumptions Codex allowed:
+
+- **Hermes's log is not files.** The `TranscriptSource` defaults (rglob, line reads, string
+  timestamps) assume JSONL-on-disk. 0009's seam anticipated this ("a host with a different
+  container overrides `discover`, `read_records`, `timestamp`"), but no host had exercised it.
+- **Claude Code's roles lie.** A tool result is logged as a *user*-typed record. Any
+  classification keyed on role alone would put tool output in the conversation transcript the
+  memory job reads.
+
+## Decision
+
+### 1. The host CLI is built from a declaration, not copied
+
+Five binaries share one verb set — `retrieve`, `install-instruction`, `prepare`, `commit`,
+`verify-resources`, `doctor`, `docs` — because the behavior behind every verb is host-agnostic.
+So the parser and handlers move to `memu.hosts.host_cli`, built from a `HostSpec`: the host id,
+the session-log default, the instruction-file default, and the docs package. A host's `cli.py`
+is now the spec plus `main`, ~40 lines; `memu-codex` is rebuilt on the same spec with byte-
+identical behavior.
+
+The standing-instruction text (ADR 0009's managed block) is likewise parameterized on the host
+binary rather than hardcoding `memu-codex`; each host's block names its own `retrieve`, and the
+per-binary begin-marker means two hosts pointed at one file manage two independent blocks.
+Codex's rendered block is unchanged, so already-installed markers still match and upgrade in
+place.
+
+What stays per host is exactly what 0009 predicted — a `TranscriptSource` — plus the two paths
+(session log, instruction file) and the packaged guides. Cursor's `discover` is narrowed to
+`*/agent-transcripts/**/*.jsonl` (the project dirs also hold canvases and terminal logs);
+Hermes overrides the container seam wholesale: sessions are *virtual paths* keyed by session
+id, `read_records` serializes message rows to JSON lines ordered by insertion id, and
+`discover` orders by last activity so the manifest's early-stop stays sound. The database is
+opened **read-only** — the bridging task must never contend for Hermes's WAL write lock. The
+line-count cursor carries over untouched: message rows are append-only per session, so "lines
+seen" is "rows seen."
+
+### 2. Working trees are per host; the store stays shared
+
+0009's open issue is settled by removing the sharing, not by locking: every host's `Layout`
+gets its own base directory, `~/.memu/hosts/<host>/`, holding its jobs, sliced sessions,
+mirrors, manifests, and touched-file log. Concurrent bridging runs of different hosts touch
+disjoint trees. **Codex keeps `~/.memu`**: its job-file paths are baked into users' already-
+scheduled task prompts (the exact fragility 0009's `PATH`-command decision was protecting
+against — the prompt references `~/.memu/jobs/*.txt` literally), and breaking every existing
+install to make five directories symmetrical is a bad trade. The asymmetry is recorded in
+`HostSpec.base_dir` with a comment saying why.
+
+What is *not* per host: `~/.memu/config.env` and the store behind `MEMU_DB`. That is the
+point of the whole exercise — a session mined from Claude Code tonight is retrievable from
+Cursor tomorrow. The install guides instruct an agent that finds an existing `config.env` to
+reuse it as is, because a second host writing a second store/provider would silently split the
+embedding space (0009's core invariant).
+
+### 3. Classification is by record shape, not role
+
+Each host's `classify` encodes its log's actual semantics, pinned by tests with hand-written
+records in the host's real shape:
+
+- **Claude Code**: block type decides — `text` (or a raw-string user message) is conversation;
+  `tool_use`/`tool_result` are tool records regardless of the wrapping role; `thinking` blocks,
+  `isMeta` user records, and all non-message types are dropped.
+- **Cursor**: a record with prose is conversation even when it also carries the `tool_use`
+  blocks it narrates; only bare tool-block records go to the tool transcript. No timestamps
+  exist, so the manifest records `null` and the line count alone drives incrementality.
+- **OpenClaw**: `type: message` with role user/assistant is conversation, role `toolResult` is
+  a tool record; session headers, compaction summaries, and extension entries are dropped.
+  Timestamps may be ISO strings or epoch millis; both normalize.
+- **Hermes**: role `tool`, and assistant rows carrying only `tool_calls`, are tool records;
+  user/assistant rows with content are conversation; `system` rows are dropped. Epoch-seconds
+  timestamps normalize to ISO.
+
+## What this changes
+
+- Four new console scripts — `memu-claude-code`, `memu-cursor`, `memu-openclaw`,
+  `memu-hermes` — each with packaged `INSTALL.md` / `BRIDGING_TASK.md` guides printable via
+  `<binary> docs`, alongside the unchanged `memu-codex`.
+- `memu.hosts.host_cli` (new): `HostSpec` + the shared parser/handlers. `codex/cli.py`
+  shrinks to its spec; its public names (`build_parser`, `AGENTS_MD`, `HOST`,
+  `VERIFY_COMMAND`) survive.
+- `memu.hosts.instruction`: `INSTRUCTION`/`BEGIN` constants become `instruction(binary)` /
+  `begin(binary)` templates; `install`/`patch`/`register` take the binary.
+- `memu.hosts.base.TranscriptSource` gains `exists()` (default: root is a directory) so a
+  SQLite-backed host can gate `prepare` on its file instead.
+- New host packages: `hosts/claude_code`, `hosts/cursor`, `hosts/openclaw`, `hosts/hermes` —
+  each a `sessions.py`, a spec-sized `cli.py`, and the two guides.
+
+## Consequences
+
+Positive:
+
+- The 0009 claim is now demonstrated: four hosts, zero pipeline forks, and the next host is a
+  `classify` method, two paths, and two markdown files.
+- Concurrent bridging across hosts is safe by construction (disjoint trees), with no locking
+  protocol to get wrong.
+- One instruction text and one CLI surface to improve; all five binaries pick up fixes at once.
+
+Negative / costs:
+
+- Codex's `~/.memu` vs everyone else's `~/.memu/hosts/<host>` is a visible asymmetry, carried
+  for compatibility. A future major release could migrate Codex in.
+- The recall-file mirror is written once per host per run instead of once per machine —
+  redundant disk writes, accepted for isolation.
+- Cursor's inject seam is per project (no global file), so its instruction install is a
+  per-project step the guides must (and do) call out.
+- Host log formats are observed, not contracted. OpenClaw already has a SQLite session target
+  behind a flag; if it becomes the default, that host needs the Hermes treatment. The
+  per-host fixture tests localize such breaks.
+
+## Open issues (deferred)
+
+- **Same-host concurrency.** Two bridging runs of the *same* host still race on that host's
+  tree; scheduled tasks make this unlikely, and per-run lock files remain available if it
+  bites.
+- **IDE-container hosts.** Cursor's Composer history (`state.vscdb`) and any host whose log
+  lives inside an editor's private state would need the SQLite treatment plus a stability
+  story for schema drift; not attempted.
+- **Session-dir env vars.** OpenClaw (`OPENCLAW_STATE_DIR`) and Hermes (`HERMES_HOME`) can
+  relocate their logs; the adapters take `--session-dir` rather than reading the host's env,
+  keeping the contract explicit. The guides say when to pass it.
+
+## Related ADRs
+
+- Builds on `docs/adr/0008-two-integration-surfaces-hooks-and-api.md` — each new host binds
+  the same two seams.
+- Builds on `docs/adr/0009-codex-packaging-cli-and-config.md` — settles its "concurrent
+  hosts" open issue via per-host working trees; keeps its distribution, CLI-command, and
+  config decisions unchanged.

memu_cli-0.3.0/docs/adr/0011-generic-host-adapter.md

@@ -0,0 +1,85 @@
+ADR 0011: A Generic Host Adapter — Detect First, Then Bind What Works
+
+- Status: Accepted
+- Date: 2026-07-16
+- Builds on: ADR 0008 (two seams), ADR 0010 (multi-host adapters, shared CLI builder)
+- Scope: how memU integrates with agents that have **no dedicated adapter**. It does not
+  change the five dedicated hosts or the pipeline.
+
+## Context
+
+ADR 0010 shipped five dedicated adapters and noted the recipe for a sixth: a `classify`
+method, two paths, two markdown files. That recipe assumes someone writes the adapter. The
+long tail of agents — new CLIs appear monthly — will mostly never get one, yet many of them
+are integrable *today*, because the ecosystem has converged on a handful of session-log
+dialects and a handful of instruction-file names.
+
+Two observations make a generic adapter viable:
+
+1. **Session logs cluster into ~5 JSONL dialects.** Payload-wrapped (Codex lineage), typed
+   message trees (OpenClaw/pi lineage), typed block records (Claude Code lineage),
+   role+message blocks (Cursor lineage), and flat OpenAI-client chat rows. A sniffing
+   `classify` that tries these in order covers most JSONL-logging agents without any
+   per-agent code.
+2. **The two seams degrade independently.** An agent with a readable session log gets
+   *memorization* (the record seam) even if we cannot find its instruction file; an agent
+   with only an `AGENTS.md`/`CLAUDE.md`/`SOUL.md`-style file gets *retrieval* (the inject
+   seam) even if its sessions are unreadable (SQLite, editor state, or absent). Partial
+   integration is still integration — but only if the user is told which half they got.
+
+## Decision
+
+One more binary, `memu-agent` (package `memu.hosts.generic`), with the shared verb surface
+plus one new verb:
+
+- **`detect` probes before anything binds.** With no argument it surveys `~` for agent
+  directories; with a path it probes that directory. For each candidate it answers the two
+  questions in order — *is there a session log whose records sniff as a known dialect?*
+  (memorization), and if not or additionally, *is there an instruction file to patch?*
+  (retrieval) — and prints an explicit per-agent verdict: memorization works / retrieval
+  works / both / neither, with the found paths and the exact next command. Directories of
+  the five dedicated hosts are redirected to their own binaries. Sessions in containers the
+  sniffer cannot read (SQLite and friends) are reported as such — the Hermes precedent, not
+  silence.
+- **The transcript source sniffs per record.** `GenericTranscriptSource.classify` tries the
+  five dialects in order; a record matching none is `OTHER`. This is the same fail-closed
+  posture the dedicated adapters take with their hosts' metadata records: the mining jobs
+  see only what provably is conversation or tool traffic, so a half-recognized log degrades
+  to less input, never to garbage input.
+- **Nothing is defaulted that detect must find.** `prepare --session-dir` is *required* (the
+  `HostSpec` marks no universal location), and `install-instruction` takes the `--path`
+  detect reported. The one machine-specific value the bridging prompt carries is that
+  session dir — a deliberate, documented exception to ADR 0009's "nothing machine-specific
+  in the prompt", because for an unknown agent there is no `PATH`-stable name to hide it
+  behind.
+- **Several generic agents share one binary, not one working tree.** The default tree is
+  `~/.memu/hosts/agent/`; integrating a second unknown agent means passing
+  `--base-dir ~/.memu/hosts/<name>` in that agent's task, keeping ADR 0010's isolation
+  guarantee.
+
+## Consequences
+
+Positive:
+
+- Any agent logging a known JSONL dialect integrates with zero new code, and any agent with
+  a recognizable instruction file gets retrieval regardless.
+- The user always learns *which* seams work and why — the detect report is the contract,
+  so a retrieval-only integration is a stated outcome rather than a silent half-failure.
+- `detect` doubles as the scouting tool for new dedicated adapters: an unrecognized-dialect
+  or SQLite report is exactly the evidence a sixth adapter starts from.
+
+Negative / costs:
+
+- Sniffing is heuristic. A new dialect classifies as `OTHER` (missed memories, safe), and a
+  pathological log could mis-bucket records (wrong-track memories, bounded by the dialects'
+  mutual exclusivity). The dedicated adapters remain the correctness bar.
+- `detect`'s survey reads directory listings across `~/.*` (capped per directory); it is
+  read-only but not free, and its skip-list of non-agent dirs needs occasional tending.
+- The required `--session-dir` bakes one machine-specific path into the generic bridging
+  prompt — accepted, see above.
+
+## Related ADRs
+
+- `docs/adr/0010-multi-host-adapters.md` — the shared CLI builder (`HostSpec`) this reuses,
+  extended here with `register_extra` (host-specific subcommands) and required-when-blank
+  `session_dir`.

{memu_cli-0.2.0 → memu_cli-0.3.0}/docs/adr/README.md

@@ -9,3 +9,5 @@
 - [0007: Split Memorize/Retrieve into Three Independent Lines on a Layered Wiki-Graph Kernel](0007-three-independent-memory-lines-wiki-graph.md)
 - [0008: Trajectory as the Source — Zero-Code Hooks over a Programmatic API](0008-two-integration-surfaces-hooks-and-api.md)
 - [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)

{memu_cli-0.2.0 → memu_cli-0.3.0}/npm/README.md

@@ -38,14 +38,14 @@ State persists in a local SQLite database (`./data/memu.sqlite3` by default), so
 
 ## How it works
 
-This npm package is a thin launcher (a few kB, no dependencies). The engine is the PyPI package [`memu-cli`](https://pypi.org/project/memu-cli/) — the CLI release channel of [`memu-py`](https://pypi.org/project/memu-py/), same module, versioned independently, with prebuilt wheels for Linux (x86_64/aarch64), macOS (Intel/Apple Silicon), and Windows. The shim finds a runner and delegates, in order:
+This npm package is a thin launcher (a few kB, no dependencies). The engine is the PyPI package [`memu-cli`](https://pypi.org/project/memu-cli/) — the memU engine itself, with prebuilt wheels for Linux (x86_64/aarch64), macOS (Intel/Apple Silicon), and Windows. The shim finds a runner and delegates, in order:
 
 1. `$MEMU_PYTHON -m memu` — explicit interpreter override
 2. `uvx --from memu-cli memu` — no install needed, cached by uv (recommended)
 3. `pipx run --spec memu-cli memu` — no install needed, cached by pipx
 4. `python3 -m memu` — requires `pip install memu-cli`
 
-Using Python already? Skip npm entirely: `uvx --from memu-cli memu --help`, or `pip install memu-cli`. For the library API (`MemoryService`, Postgres backends), use [`memu-py`](https://pypi.org/project/memu-py/) — but install only one of the two in a given environment; they ship the same `memu` module.
+Using Python already? Skip npm entirely: `uvx --from memu-cli memu --help`, or `pip install memu-cli`. The same package carries the library API (`MemoryService`, Postgres backends) — one install covers CLI, host adapters, and library use.
 
 See the [main README](https://github.com/NevaMind-AI/MemU#readme) for the memory model, library API, and self-hosting options.
 

{memu_cli-0.2.0 → memu_cli-0.3.0}/npm/bin/memu.js

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-// memu-cli: thin launcher for the PyPI package `memu-cli` (the CLI release
-// channel of the memU engine; same module as memu-py, versioned independently).
+// memu-cli: thin launcher for the PyPI package `memu-cli` (the memU engine).
 //
 // The memU engine is Python (>= 3.13). This shim finds a runner and delegates,
 // in order of preference:

{memu_cli-0.2.0 → memu_cli-0.3.0}/npm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memu-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI for memU \u2014 personal memory as files. Thin launcher for the PyPI package memu-cli.",
   "bin": {
     "memu": "bin/memu.js"