Merge pull request #48 from afx-team/codex/agent-session-sync

feat: add agent session sync

Author: ch-liuzhide

AGENTS.md

@@ -113,6 +113,10 @@ def test_retrieve_returns_sorted_memories():
 
 ## Conventions (SHOULD)
 
+### UI / CLI Parity
+- New Web Console features **SHOULD** have a corresponding `hebb` CLI command for the same core workflow.
+- If CLI parity is intentionally skipped, document why the feature is UI-only or why a CLI would not be useful.
+
 ### Visual Documentation
 - Use **mermaid diagrams** for architecture, data flow, and component relationships
 - Example:
@@ -176,4 +180,4 @@ Before marking any task complete, verify:
 | Public documentation | `repo_pages/` | VuePress page format |
 | Paper summary | `reports/papers/` | See `reports/papers/.template.md` |
 | Project analysis | `reports/analysis/` | See `reports/analysis/.template.md` |
-| Architecture design | `reports/design/` | See `reports/design/.template.md` |
+| Architecture design | `reports/design/` | See `reports/design/.template.md` |

README.md

@@ -81,6 +81,13 @@ Open <http://localhost:8321/> for the Web Console.
   <img src="repo_pages/public/web-console-hero.jpg" alt="Hebb Mind Web Console — partitioned memories and tag graph" width="760">
 </p>
 
+Use **Agent Sync** in the Web Console to make Hebb Mind the shared memory hub for Claude Code and Codex. It collects local session history from both tools, shows synced vs pending turns, and imports pending turns into the Hebb Mind database. The same workflow is available from the CLI:
+
+```bash
+hebb agent-sync list --host codex
+hebb agent-sync sync --host codex --dry-run
+```
+
 ### Full experience (5 min) — enable LLM consolidation
 
 Consolidation, conflict resolution, and tag extraction need an LLM backend. The gate is `llm_model` — until it's set, those endpoints are a no-op (see [#consolidation-no-op](https://afx-team.github.io/hebb-mind/troubleshooting.html)). A hosted provider also needs `llm_api_key`; a local model (e.g. Ollama via `llm_base_url`) does not.
@@ -106,6 +113,8 @@ pipx install 'hebb-mind[pg]'           # + PostgreSQL/pgvector
 pipx upgrade hebb-mind                 # upgrade later
 hebb claude-code install --scope user  # Claude Code: hooks-based recall + turn capture
 hebb codex install                     # Codex: project MCP + automatic memory hooks
+hebb agent-sync list                   # Audit Claude Code / Codex session sync status
+hebb agent-sync sync --dry-run         # Preview historical session import
 ```
 
 Docker, one-line install, and source build: [Installation Guide](https://afx-team.github.io/hebb-mind/guide/installation.html).

README_ZH.md

@@ -81,6 +81,13 @@ curl -X POST http://localhost:8321/api/v1/search \
   <img src="repo_pages/public/web-console-hero.jpg" alt="Hebb Mind Web 控制台 — 分区记忆与标签图谱" width="760">
 </p>
 
+在 Web 控制台中使用 **Agent 同步**，可把 Hebb Mind 作为 Claude Code 与 Codex 的共享记忆中转站。它会收集两类工具的本机会话历史，显示已同步与待同步回合，并把待处理回合导入 Hebb Mind 数据库。同一流程也可通过 CLI 使用：
+
+```bash
+hebb agent-sync list --host codex
+hebb agent-sync sync --host codex --dry-run
+```
+
 ### 完整体验（5 分钟）— 启用 LLM 巩固
 
 记忆巩固、冲突解决、标签提取需要一个 LLM 后端。开关由 `llm_model` 决定 —— 未设置前这些接口为 no-op（详见 [#consolidation-no-op](https://afx-team.github.io/hebb-mind/zh/troubleshooting.html)）。托管 provider 还需要 `llm_api_key`；本地模型（例如通过 `llm_base_url` 接入的 Ollama）则不需要。
@@ -106,6 +113,8 @@ pipx install 'hebb-mind[pg]'           # 启用 PostgreSQL/pgvector
 pipx upgrade hebb-mind                 # 后续升级
 hebb claude-code install --scope user  # Claude Code：基于 hooks 的召回 + 回合写入
 hebb codex install                     # Codex：项目级 MCP + 自动记忆 hooks
+hebb agent-sync list                   # 查看 Claude Code / Codex 会话同步状态
+hebb agent-sync sync --dry-run         # 预览历史会话导入
 ```
 
 Docker、一键脚本、源码安装详见 [安装指南](https://afx-team.github.io/hebb-mind/zh/guide/installation.html)。

repo_pages/.vitepress/config.mts

@@ -313,6 +313,7 @@ function guideSidebar(prefix = '') {
         { text: prefix ? '切换 Embedding 模型' : 'Switch Embedding Model', link: `${prefix}/guide/switch-embedding-model` },
         { text: 'Claude Code', link: `${prefix}/guide/claude-code` },
         { text: 'Codex', link: `${prefix}/guide/codex` },
+        { text: prefix ? 'Agent 同步' : 'Agent Sync', link: `${prefix}/guide/agent-sync` },
         { text: prefix ? 'MCP 集成' : 'MCP Integration', link: `${prefix}/guide/mcp-integration` },
         { text: prefix ? 'Web 控制台' : 'Web Console', link: `${prefix}/guide/web-console` },
         { text: prefix ? '从其他系统迁移' : 'Migration from mem0 / Letta / Zep', link: `${prefix}/guide/migration` },

repo_pages/api/cli.md

@@ -114,6 +114,34 @@ hebb console            # open in browser
 hebb console --print    # print URL only (CI / SSH friendly)
 ```
 
+## hebb agent-sync
+
+Collect local Claude Code and Codex session history, show sync state, and import pending turns into Hebb Mind. This is the CLI counterpart to the Web Console **Agent Sync** page and uses the same `/api/v1/agent-sync/*` endpoints.
+
+```bash
+hebb agent-sync list [--host all|claude-code|codex] [--limit 100] [--json] [--url URL]
+hebb agent-sync sync [--host all|claude-code|codex] [--id SESSION_ID]... [--limit 100] [--dry-run] [--json] [--url URL]
+```
+
+| Option | Applies to | Description |
+|--------|------------|-------------|
+| `--host` | `list`, `sync` | Filter to one source. `claude-code` maps to the API host `claude_code`. |
+| `--limit` | `list`, `sync` | Maximum sessions to scan. |
+| `--id` | `sync` | Sync only specific opaque session ids returned by `list --json`. May be repeated. |
+| `--dry-run` | `sync` | Report pending turns without writing memories. |
+| `--json` | `list`, `sync` | Print the raw API payload for scripts. |
+| `--url` | `list`, `sync` | Override the server URL, useful for dev servers on non-default ports. |
+
+Common workflow:
+
+```bash
+hebb agent-sync list --host codex
+hebb agent-sync sync --host codex --dry-run
+hebb agent-sync sync --host codex
+```
+
+Synced turns land in `mem_hippocampus` with `source` set to `sync:codex` or `sync:claude_code`, then follow the normal consolidation and recall lifecycle. See [Agent Sync](../guide/agent-sync.md) for the full workflow.
+
 ## hebb doctor
 
 Run a one-shot health check covering Python version, config file, workspace, LLM, embedding model cache, web console assets, server reachability, and Claude Code / Codex MCP registration.

repo_pages/guide/agent-sync.md

@@ -0,0 +1,126 @@
+---
+description: "Use Hebb Mind as the shared memory hub for Claude Code and Codex: collect local session history, sync pending turns, and keep the Web Console and CLI in parity."
+---
+
+# Agent Sync
+
+Agent Sync turns Hebb Mind into the shared memory hub between **Claude Code** and **Codex**.
+
+The normal hooks capture new turns after installation. Agent Sync covers the other half of the workflow: it scans local session history that already exists on disk, shows what has and has not reached Hebb Mind, and imports pending turns into the same database used by recall, consolidation, and search.
+
+```mermaid
+flowchart LR
+    Claude["Claude Code sessions"]
+    Codex["Codex sessions"]
+    Hub["Hebb Mind<br/>mem_hippocampus"]
+    Recall["Recall from<br/>Claude Code / Codex / MCP"]
+
+    Claude -->|collect + sync| Hub
+    Codex -->|collect + sync| Hub
+    Hub -->|shared memory| Recall
+```
+
+## When to use it
+
+Use Agent Sync when you want to:
+
+- populate Hebb Mind from past Claude Code or Codex conversations;
+- verify which local sessions have already been written into Hebb Mind;
+- move memories from one agent surface to another through Hebb Mind;
+- run the same workflow from either the Web Console or the `hebb` CLI.
+
+Agent Sync does not replace the live hooks. Install the hooks for future capture, then use Agent Sync to backfill history or audit sync state.
+
+```bash
+hebb claude-code install --scope user
+hebb codex install
+```
+
+## Web Console workflow
+
+Open the console:
+
+```bash
+hebb console
+```
+
+Then go to **Agent Sync**.
+
+1. Choose **All software**, **Claude Code**, or **Codex**.
+2. Read the hub flow: **Source software → Hebb Mind → Available to Claude Code / Codex**.
+3. Review the sync queue. Each row shows project, transcript path, synced turns, pending turns, and update time.
+4. Click **Sync pending** to import all pending turns for the selected source, or **Sync** on a single session.
+
+The page intentionally replaces the old Claude Code-only memory browser as the primary cross-agent workflow. Claude Code file memory and Hebb Mind database memory are different systems; Agent Sync makes the Hebb Mind database the shared hub.
+
+## CLI workflow
+
+The CLI mirrors the Web Console actions.
+
+List sessions and sync state:
+
+```bash
+hebb agent-sync list
+hebb agent-sync list --host claude-code
+hebb agent-sync list --host codex
+```
+
+Dry-run a sync before writing:
+
+```bash
+hebb agent-sync sync --host codex --dry-run
+```
+
+Sync pending turns:
+
+```bash
+hebb agent-sync sync --host claude-code
+hebb agent-sync sync --host codex
+```
+
+For scripts or troubleshooting, use JSON output:
+
+```bash
+hebb agent-sync list --host codex --json
+hebb agent-sync sync --host codex --dry-run --json
+```
+
+If you run a development server on a non-default port, pass it explicitly:
+
+```bash
+hebb agent-sync list --url http://127.0.0.1:8765
+```
+
+## What gets stored
+
+Synced turns are written to the working-memory inbox, `mem_hippocampus`, so the normal lifecycle still applies: inspect, consolidate, recall, and forget.
+
+Each imported memory includes:
+
+| Field | Value |
+|---|---|
+| `source` | `sync:claude_code` or `sync:codex` |
+| `partition_id` | `mem_hippocampus` |
+| `metadata.host` | `claude_code` or `codex` |
+| `metadata.session_id` | Source session identifier |
+| `metadata.turn` | Turn index used for dedupe |
+| `metadata.source_path` | Local transcript path |
+| `metadata.tools` / `metadata.mcps` | Tool and MCP names observed in the turn |
+
+Agent Sync deduplicates by `host + session_id + turn`, and also avoids duplicating older hook writes that did not yet include a `host` field.
+
+## Troubleshooting
+
+**No sessions found.** Make sure the sessions exist locally on the same machine as the Hebb Mind service. Agent Sync currently scans the local Claude Code and Codex transcript locations.
+
+**The CLI says the Agent Sync API is missing.** The running service is probably older than the checkout or package that provided your CLI. Restart the service:
+
+```bash
+hebb service restart
+```
+
+If you are using a dev server, pass `--url`.
+
+**Hook output still shows an old command.** Codex and Claude Code load hook configuration at session startup. Start a new session or reload hooks after reinstalling the integration.
+
+**This is local-first.** The console displays local transcript paths. Do not expose the console on a public network without authentication; see [Web Console](./web-console.md#authentication).

repo_pages/guide/web-console.md

@@ -1,10 +1,10 @@
 ---
-description: "Browse, search, and edit your AI agent memory in the browser: the Hebb Mind Web Console bundles hybrid retrieval, a knowledge graph view, and live config on port 8321."
+description: "Browse, search, sync, and tune AI agent memory in the browser: the Hebb Mind Web Console bundles Agent Sync, hybrid retrieval, a knowledge graph view, and live config on port 8321."
 ---
 
 # Web Console
 
-The Web Console is a single-page app that ships inside the Hebb Mind binary. It gives you a browseable view of your memories, a search box wired to the same hybrid retrieval that powers the API, a graph view of your knowledge graph, and a settings panel for changing config without touching JSON.
+The Web Console is a single-page app that ships inside the Hebb Mind binary. It gives you a browseable view of your memories, Agent Sync for Claude Code and Codex session history, a search box wired to the same hybrid retrieval that powers the API, a graph view of your knowledge graph, and a settings panel for changing config without touching JSON.
 
 ## Access
 
@@ -40,7 +40,7 @@ The whole stack reads from your resolved workspace (run `hebb config get workspa
 
 ## Tour
 
-The sidebar is organised around the memory lifecycle. The first four entries — **Manage**, **Activate**, **Consolidate**, **Forget** — are the write → recall → consolidate → forget loop; a divider separates them from **CC Memory**, **System**, and a link out to the **Docs**. Each entry is a hash route, so you can deep-link straight to it.
+The sidebar is organised around the memory lifecycle. **Manage**, **Activate**, **Agent Sync**, **Consolidate**, and **Forget** cover browse/write → recall → cross-agent sync → consolidate → forget; a divider separates them from **System** and a link out to the **Docs**. Each entry is a hash route, so you can deep-link straight to it.
 
 ### Manage (`#manage`)
 
@@ -59,6 +59,17 @@ If the stat band reads zero on a fresh install, you're probably in the wrong wor
 
 Recall, end to end. A **recall test** at the top lets you run a semantic search with per-query sliders for `relevance`, `importance`, and `recency`, and renders the scored results. Below it sit the global **recall parameters** — the recall-pipeline toggles, cross-encoder rerank, and the default scoring weights — so you can tune against real queries and then persist what works.
 
+### Agent Sync (`#agent-sync`)
+
+The cross-agent memory hub for Claude Code and Codex.
+
+- Choose **All software**, **Claude Code**, or **Codex**.
+- Read the flow as **Source software → Hebb Mind → Available to Claude Code / Codex**.
+- Inspect the sync queue: project, transcript path, synced turns, pending turns, and update time.
+- Click **Sync pending** to import all pending turns for the current filter, or **Sync** on one session.
+
+This is the primary UI for making Hebb Mind the shared memory layer across agent tools. The matching CLI commands are `hebb agent-sync list` and `hebb agent-sync sync`; see [Agent Sync](./agent-sync.md).
+
 ### Consolidate (`#consolidate`)
 
 Consolidation runs automatically on a daily cron. This page gives you an **Organize now** trigger to run it on demand and stream the run log live, the **run records** of past consolidations, and the **consolidation config**.
@@ -70,10 +81,6 @@ The forgetting counterpart of Consolidate. A **Clean up now** trigger runs a swe
 <!-- TODO(asset): screenshot of the Manage → Graph tab with a non-trivial graph rendered (5+ tag clusters). Save as repo_pages/public/console-graph.png, then uncomment the image below. -->
 <!-- ![Graph view](../public/console-graph.png) -->
 
-### CC Memory (`#cc-memory`)
-
-Browse and edit Claude Code's file-based memory documents directly on disk.
-
 ### System (`#system`)
 
 Infrastructure config, grouped into tabs: **LLM**, **Embedding**, **Storage**, and **Server**.
@@ -104,10 +111,18 @@ This requires an LLM key — see [Troubleshooting](../troubleshooting.md#consoli
 
 **Change the LLM model without restarting.** System → LLM → enter a LiteLLM string (e.g. `anthropic/claude-3-haiku-20240307`) → save. If the field shows `restart_required`, run `hebb service restart`.
 
+**Backfill Claude Code or Codex sessions.** Open Agent Sync → pick the source software → click **Sync pending**. For headless use:
+
+```bash
+hebb agent-sync list --host codex
+hebb agent-sync sync --host codex --dry-run
+hebb agent-sync sync --host codex
+```
+
 ## When to use the Console vs. the CLI vs. the API
 
-- **Console** — exploration, tuning weights, sanity-checking ingest, demos.
-- **CLI (`hebb …`)** — install, configuration, running the server, integration setup.
+- **Console** — exploration, tuning weights, sanity-checking ingest, syncing agent sessions, demos.
+- **CLI (`hebb …`)** — install, configuration, running the server, integration setup, and the same Agent Sync workflow in headless form.
 - **REST API** — anything programmatic, CI, custom UIs.
 
 All three operate on the same workspace simultaneously. Updates from one show up in the others on next refresh.

repo_pages/index.md

@@ -36,8 +36,8 @@ features:
     title: Built-in Web Console
     details: Single-page app for memory CRUD, search, partitions, and graph view. Lives at http://localhost:8321/ — no separate deploy.
   - icon: 🔌
-    title: REST + MCP + Claude Code hooks
-    details: Three-line install gives Claude Code or Codex automatic cross-session recall and turn capture, backed by MCP memory tools. REST docs at /docs.
+    title: REST + MCP + Agent Sync
+    details: Claude Code and Codex get automatic recall and turn capture through hooks, explicit memory tools over MCP, and historical session backfill through the Agent Sync hub.
 ---
 
 <div class="hippo-home">

repo_pages/public/llms.txt

@@ -19,6 +19,7 @@ Headline benchmark results (reproducible via the `eval/` harness): LongMemEval r
 - [Switch the Embedding Model](https://afx-team.github.io/hebb-mind/guide/switch-embedding-model.html): Use local sentence-transformers or a LiteLLM API embedding provider, handle dimension changes, and re-embed with resume.
 - [Claude Code Integration](https://afx-team.github.io/hebb-mind/guide/claude-code.html): Give Claude Code cross-session memory via the MCP server plus session hooks for automatic recall, turn capture, and consolidation.
 - [Codex Integration](https://afx-team.github.io/hebb-mind/guide/codex.html): Give Codex automatic cross-session recall and turn capture with native hooks, plus explicit memory tools over MCP.
+- [Agent Sync](https://afx-team.github.io/hebb-mind/guide/agent-sync.html): Use Hebb Mind as the shared memory hub for Claude Code and Codex by collecting local session history and syncing pending turns.
 - [MCP Integration](https://afx-team.github.io/hebb-mind/guide/mcp-integration.html): Connect Claude Code, Codex, Cursor, and Claude Desktop to long-term memory over MCP — write, recall, and consolidate.
 - [Web Console](https://afx-team.github.io/hebb-mind/guide/web-console.html): Browser UI bundled with the service (port 8321) — memory CRUD, hybrid search, partitions, a knowledge-graph view, and live config.
 - [Migration from mem0 / Letta / Zep](https://afx-team.github.io/hebb-mind/guide/migration.html): Concept and API mapping, before/after code, data import, and an honest gap analysis.
@@ -39,7 +40,7 @@ Headline benchmark results (reproducible via the `eval/` harness): LongMemEval r
 - [Knowledge Graph API](https://afx-team.github.io/hebb-mind/api/graph.html): Inspect tags, query neighbors by depth, find shortest paths, and export nodes and edges.
 - [Admin API](https://afx-team.github.io/hebb-mind/api/admin.html): Trigger consolidation/forgetting, read stats, restart, and poll health/status.
 - [Config API](https://afx-team.github.io/hebb-mind/api/config.html): Read and update config at runtime — LLM and embedding settings, masked secrets, connectivity tests.
-- [CLI Reference](https://afx-team.github.io/hebb-mind/api/cli.html): The `hebb` command — setup, model download, background service, MCP/Claude Code wiring, and config.
+- [CLI Reference](https://afx-team.github.io/hebb-mind/api/cli.html): The `hebb` command — setup, model download, background service, MCP/Claude Code/Codex wiring, Agent Sync, and config.
 
 ## Advanced