oceanbase · happyhust · May 28, 2026 · May 29, 2026 · May 29, 2026 · May 29, 2026
diff --git a/.env.example b/.env.example
diff --git a/.env.example.full b/.env.example.full
diff --git a/.gitignore b/.gitignore
@@ -217,6 +217,7 @@ api_server.log
 # Server data directories (if any)
 server_data/
 api_data/
+seekdb_data/
 
 # Server backups
 server_backup/

diff --git a/Makefile b/Makefile
@@ -216,7 +216,7 @@ ENV_SERVER_WORKERS := $(shell grep -E '^POWERMEM_SERVER_WORKERS=' .env 2>/dev/nu
 
 # Use values from .env if they exist and are non-empty, otherwise use defaults
 SERVER_HOST := $(or $(ENV_SERVER_HOST),0.0.0.0)
-SERVER_PORT := $(or $(ENV_SERVER_PORT),8000)
+SERVER_PORT := $(or $(ENV_SERVER_PORT),8848)
 SERVER_WORKERS := $(or $(ENV_SERVER_WORKERS),4)
 
 server-start: ## Start the PowerMem API server
@@ -401,21 +401,21 @@ docker-run: ## Run Docker container
 	fi
 	docker run -d \
 		--name powermem-server \
-		-p 8000:8000 \
+		-p 8848:8848 \
 		-v $$(pwd)/.env:/app/.env:ro \
 		--env-file .env \
 		$(DOCKER_IMAGE):$(DOCKER_TAG) || \
 		(echo "Container may already exist. Use 'make docker-stop' first or 'make docker-restart'"; exit 1)
 	@echo "✓ Container started"
-	@echo "Server running at http://localhost:8000"
-	@echo "API docs at http://localhost:8000/docs"
+	@echo "Server running at http://localhost:8848"
+	@echo "API docs at http://localhost:8848/docs"
 
 docker-up: ## Start services using docker-compose
 	@echo "Starting services with docker-compose..."
 	docker-compose -f $(DOCKER_COMPOSE_FILE) up -d
 	@echo "✓ Services started"
-	@echo "Server running at http://localhost:8000"
-	@echo "API docs at http://localhost:8000/docs"
+	@echo "Server running at http://localhost:8848"
+	@echo "API docs at http://localhost:8848/docs"
 
 docker-down: ## Stop services using docker-compose
 	@echo "Stopping services with docker-compose..."

diff --git a/README.md b/README.md
@@ -44,7 +44,7 @@ PowerMem ships first-party plugins for the most common AI clients. All of them p
 | Client / framework | One-line install | Mode |
 |--------------------|------------------|------|
 | OpenClaw (ClawdBot) | `openclaw plugins install memory-powermem` | CLI (default), HTTP optional |
-| Claude Code | `git clone https://github.com/oceanbase/powermem && claude --plugin-dir powermem/apps/claude-code-plugin` | HTTP (default), MCP optional |
+| Claude Code | `git clone https://github.com/oceanbase/powermem`, then tell Claude Code: *"Read and follow `apps/claude-code-plugin/SETUP.md`"* ([details](#claude-code)) | HTTP (default), MCP optional |
 | Cursor / VS Code / Codex / Windsurf / GitHub Copilot | Install the [PowerMem VS Code extension](apps/vscode-extension/) and run **PowerMem: Link to AI tools** | MCP or HTTP, per client |
 | Claude Desktop / Cline / any MCP client | `uvx powermem-mcp sse` | MCP (SSE / stdio / streamable-http) |
 | LangChain / LangGraph | `pip install powermem`, see [examples](#examples) | Python SDK |
@@ -68,27 +68,26 @@ Defaults to **CLI mode** — the plugin invokes a bundled `pmem` against SQLite
 
 ### Claude Code
 
-```bash
-# From a clone of this repo
-claude --plugin-dir /path/to/powermem/apps/claude-code-plugin
+#### Fastest path — let Claude Code set itself up
+
+First download the code and enter the directory:
 
-# Or unpack a packaged release zip and pass --plugin-dir to it
-make package-claude-plugin   # builds apps/claude-code-plugin/dist/<version>.zip
+```bash
+git clone https://github.com/oceanbase/powermem
+cd powermem
 ```
 
-HTTP mode is on by default:
+Then open Claude Code in your terminal and paste this one line:
 
-- `UserPromptSubmit` -> `POST /api/v1/memories/search` and the top results are injected as `additionalContext`.
-- `SessionEnd` / `PostCompact` -> `POST /api/v1/memories` writes the transcript or compact summary.
-- No MCP setup, no Python needed on the user's machine (hooks ship as native binaries under `hooks/bin/`).
+```text
+Read and follow apps/claude-code-plugin/SETUP.md to set up PowerMem memory for Claude Code.
+```
 
-Switch to MCP mode for in-chat `search_memories` / `add_memory` tools:
+Claude Code reads [`apps/claude-code-plugin/SETUP.md`](apps/claude-code-plugin/SETUP.md), asks you for the few required secrets, and wires everything up end-to-end.
 
-```bash
-bash scripts/apply-connection-mode.sh mcp
-```
+#### Manual setup
 
-Full reference: [`apps/claude-code-plugin/README.md`](apps/claude-code-plugin/README.md).
+Prefer to wire it by hand? See the full walkthrough — environment variables, MCP mode, the `remember` / `recall` skills, Windows hooks, troubleshooting, and uninstall — in **[docs/integrations/claude_code.md](docs/integrations/claude_code.md)**.
 
 ### Cursor, VS Code, Codex, Windsurf, GitHub Copilot
 
@@ -107,7 +106,7 @@ The same extension also provides **Query memories**, **Add selection to memory**
 ### Any MCP client (Claude Desktop, Cline, …)
 
 ```bash
-uvx powermem-mcp sse                  # SSE on :8000 (recommended)
+uvx powermem-mcp sse                  # SSE on :8848 (recommended)
 uvx powermem-mcp stdio                # stdio
 uvx powermem-mcp streamable-http      # streamable HTTP
 ```
@@ -117,7 +116,7 @@ Client config (Claude Desktop and most MCP clients):
 ```json
 {
   "mcpServers": {
-    "powermem": { "url": "http://localhost:8000/mcp" }
+    "powermem": { "url": "http://localhost:8848/mcp" }
   }
 }
 ```
@@ -148,7 +147,7 @@ End-to-end runnable demos:
 
 ## Quick start (Python SDK)
 
-**Prerequisites:** Copy [.env.example](.env.example) to `.env` and set **LLM** and **embedding** credentials. The default database is SQLite; OceanBase can use **embedded SeekDB** without running a separate database service. After install, `pmem config init` walks you through the same setup interactively. See [Getting started](docs/guides/0001-getting_started.md).
+**Prerequisites:** Copy [.env.example](.env.example) to `.env` and set your **LLM** API key — that is the only required credential. The default storage is the **OceanBase** provider with no host configured, which boots **embedded seekdb** on disk (same engine, no separate server, data under `./seekdb_data`); set `OCEANBASE_HOST` to point at a remote OceanBase cluster instead, or switch to `sqlite` / `postgres`. The default embedder is a local `all-MiniLM-L6-v2` model (384 dims) that needs no API key and auto-downloads on first use. Need to tune providers or unlock advanced features? Copy [.env.example.full](.env.example.full) instead — it documents every available knob, grouped by component. After install, `pmem config init` walks you through the same setup interactively. See [Getting started](docs/guides/0001-getting_started.md).
 
 ### Install
 
@@ -204,7 +203,7 @@ Full reference: [CLI usage](docs/guides/0012-cli_usage.md).
 Uses the same `.env` as the SDK. Dashboard is served under `/dashboard/`.
 
 ```bash
-powermem-server --host 0.0.0.0 --port 8000
+powermem-server --host 0.0.0.0 --port 8848
 ```
 
 Docker / Compose: see [API Server](docs/api/0005-api_server.md) and [Docker & deployment](docker/README.md). The official image is `oceanbase/powermem-server:latest`.
@@ -226,7 +225,7 @@ Docker / Compose: see [API Server](docs/api/0005-api_server.md) and [Docker & de
 | LLM | Anthropic, OpenAI, Azure OpenAI, Gemini, Qwen (+ ASR), DeepSeek, Ollama, vLLM, SiliconFlow, Z.AI, LangChain-wrapped |
 | Embedding | OpenAI, Azure OpenAI, Qwen (+ VL multimodal, sparse), Gemini, Vertex AI, AWS Bedrock, Ollama, LM Studio, HuggingFace, Together, SiliconFlow, Z.AI, OceanBase MASS, LangChain-wrapped |
 | Rerank | Jina, Qwen, Z.AI, generic |
-| Storage | OceanBase (+ graph), embedded SeekDB, PostgreSQL/pgvector, SQLite |
+| Storage | OceanBase (+ graph), embedded seekdb, PostgreSQL/pgvector, SQLite |
 
 ---
 
@@ -239,6 +238,7 @@ Docker / Compose: see [API Server](docs/api/0005-api_server.md) and [Docker & de
 - [CLI](docs/guides/0012-cli_usage.md) — `pmem` commands, interactive shell, backup and migration
 - [Multi-agent](docs/guides/0005-multi_agent.md) — scopes, isolation, and cross-agent sharing
 - [Integrations](docs/guides/0009-integrations.md) — LangChain and other framework wiring
+- [Ecosystem integrations](docs/integrations/overview.md) — AI clients & IDEs ([Claude Code](docs/integrations/claude_code.md), …)
 - [Docker & deployment](docker/README.md) — images, Compose, and running the API server
 - [Development](docs/development/overview.md) — local setup, tests, and contributing
 
@@ -254,7 +254,7 @@ More topics: [Sub stores](docs/guides/0006-sub_stores.md), [guides index](docs/g
 | Version | Date | Notes |
 |---------|------|--------|
 | 1.2.0 | 2026-04 | Experience + Skill two-layer distillation and `distill_all()` (self-evolving memory; AppWorld +15 pts); OB MASS embedding; Qwen VL multimodal embedding; OceanBase Zero Mode compatibility; LOCOMO accuracy lifted to 87.79% |
-| 1.1.0 | 2026-04-02 | Embedded SeekDB for OceanBase storage without a separate database service; [IDE integrations](apps/README.md) (VS Code extension, Claude Code plugin) |
+| 1.1.0 | 2026-04-02 | Embedded seekdb for OceanBase storage without a separate database service; [IDE integrations](apps/README.md) (VS Code extension, Claude Code plugin) |
 | 1.0.0 | 2026-03-16 | CLI (`pmem`): memory ops, config, backup/restore/migrate, interactive shell, completions; Web Dashboard |
 | 0.5.0 | 2026-02-06 | Unified SDK/API config (pydantic-settings); OceanBase native hybrid search; memory query + list sorting; user-profile language customization |
 | 0.4.0 | 2026-01-20 | Sparse vectors for hybrid retrieval; profile-based query rewriting; schema upgrade & migration tools |

diff --git a/README_CN.md b/README_CN.md
@@ -68,27 +68,51 @@ openclaw plugins install memory-powermem
 
 ### Claude Code
 
+五步即可把 Claude Code 接入 PowerMem。默认是 **HTTP 模式** —— 记忆通过 hook 静默工作,对话里不出现工具;需要显式工具时再切到 MCP 模式(最后一步)。
+
+**第 1 步 —— 启动 PowerMem 后端。** 把 [.env.example](.env.example) 复制为 `.env`,填好 LLM API key,然后启动 HTTP 服务。hook 默认连 `http://localhost:8848`。
+
+```bash
+powermem-server --host 0.0.0.0 --port 8848
+```
+
+**第 2 步 —— 获取插件并编译 hook 二进制。** hook 以原生二进制分发,因此运行 Claude Code 的机器**无需 Python**。用 Go 1.22+ 编译一次即可(或执行 `make package-claude-plugin`,它会在打包前自动编译)。
+
+```bash
+git clone https://github.com/oceanbase/powermem
+cd powermem
+make build-claude-hook        # 产物在 apps/claude-code-plugin/hooks/bin/
+```
+
+**第 3 步 —— 把插件加载进 Claude Code。**
+
 ```bash
-# 从本仓库直接加载（开发/调试推荐）
 claude --plugin-dir /path/to/powermem/apps/claude-code-plugin
+```
 
-# 或者打包成 zip 发到目标机器，再 --plugin-dir 指向解压目录
-make package-claude-plugin   # 产物：apps/claude-code-plugin/dist/<version>.zip
+**第 4 步 —— (可选)指向团队服务并设置身份。** 本地服务用默认值即可;连远程服务时按需覆盖:
+
+```bash
+export POWERMEM_BASE_URL=https://powermem.example.com   # 默认:http://localhost:8848
+export POWERMEM_API_KEY=...                             # 仅当服务端开启鉴权时
+export POWERMEM_USER_ID=alice                           # 默认:操作系统登录名
 ```
 
-默认 **HTTP 模式**，开箱即用：
+**第 5 步 —— 开始使用。** 默认 HTTP 模式下无需任何额外操作:
+
+- `UserPromptSubmit` → `POST /api/v1/memories/search`,命中结果通过 `additionalContext` 注入当前对话(设 `POWERMEM_PROMPT_SEARCH=0` 可按轮关闭);
+- `SessionEnd` / `PostCompact` → `POST /api/v1/memories`,把整段对话或压缩摘要写回记忆。
 
-- `UserPromptSubmit` → `POST /api/v1/memories/search`，命中结果通过 `additionalContext` 注入当前对话；
-- `SessionEnd` / `PostCompact` → `POST /api/v1/memories`，把整段对话或压缩摘要写回记忆；
-- 终端机器**无需 Python**，hook 是预编译的原生二进制（macOS / Linux / Windows）。
+**验证:** 结束会话(或执行 `/compact`)后,在服务端日志中查看是否有 `POST /api/v1/memories`;在 Claude Code 里输入 `/hooks` 确认这些 hook 已注册。
 
-如果想让 Claude 在对话中显式调用 `search_memories` / `add_memory` 工具，切到 **MCP 模式** 即可：
+**可选 —— MCP 模式** 会额外提供对话内的 `search_memories` / `add_memory` 工具,以及 `/memory-powermem:remember` 与 `recall` 技能:
 
 ```bash
-bash scripts/apply-connection-mode.sh mcp
+cd apps/claude-code-plugin
+bash scripts/apply-connection-mode.sh mcp   # 之后重启 Claude Code
 ```
 
-完整说明：[`apps/claude-code-plugin/README.md`](apps/claude-code-plugin/README.md)。
+完整说明:[Claude Code 集成指南](docs/integrations/claude_code.md) · [`apps/claude-code-plugin/README.md`](apps/claude-code-plugin/README.md)。
 
 ### Cursor / VS Code / Codex / Windsurf / GitHub Copilot
 
@@ -107,7 +131,7 @@ bash scripts/apply-connection-mode.sh mcp
 ### 任意 MCP 客户端（Claude Desktop、Cline……）
 
 ```bash
-uvx powermem-mcp sse                  # SSE，默认 :8000（推荐）
+uvx powermem-mcp sse                  # SSE，默认 :8848（推荐）
 uvx powermem-mcp stdio                # stdio
 uvx powermem-mcp streamable-http      # streamable HTTP
 ```
@@ -117,7 +141,7 @@ Claude Desktop / 多数 MCP 客户端的配置：
 ```json
 {
   "mcpServers": {
-    "powermem": { "url": "http://localhost:8000/mcp" }
+    "powermem": { "url": "http://localhost:8848/mcp" }
   }
 }
 ```
@@ -148,7 +172,7 @@ pip install powermem langchain langchain-openai
 
 ## 快速开始（Python SDK）
 
-**前置条件：** 将 [.env.example](.env.example) 复制为 `.env`，配置 **LLM** 与 **向量嵌入** 凭证。默认数据库是 SQLite；OceanBase 后端可使用 **嵌入式 SeekDB**，不必额外部署数据库进程。安装后执行 `pmem config init` 可交互式生成同样的配置。详见 [入门指南](docs/guides/0001-getting_started.md)。
+**前置条件：** 将 [.env.example](.env.example) 复制为 `.env`，仅需配置 **LLM** 的 API key。默认存储是 **OceanBase** provider 且未配置 host，会自动启动 **嵌入式 seekdb**（同一引擎与 SQL，无需额外数据库进程，数据落在 `./seekdb_data`）；如需连接远端 OceanBase 集群，设置 `OCEANBASE_HOST` 即可，也可改用 `sqlite` 或 `postgres`。默认 embedder 是本地的 `all-MiniLM-L6-v2`（384 维），无需 API key，首次使用时自动下载。如需调整 provider 或开启高级特性，可改用 [.env.example.full](.env.example.full)，其中按组件分组记录了所有可调参数。安装后执行 `pmem config init` 可交互式生成同样的配置。详见 [入门指南](docs/guides/0001-getting_started.md)。
 
 ### 安装
 
@@ -204,7 +228,7 @@ pmem shell                           # 交互式 REPL
 与 SDK 共用 `.env`，Dashboard 路径 `/dashboard/`。
 
 ```bash
-powermem-server --host 0.0.0.0 --port 8000
+powermem-server --host 0.0.0.0 --port 8848
 ```
 
 Docker / Compose 部署见 [API Server](docs/api/0005-api_server.md) 与 [Docker 说明](docker/README.md)。官方镜像：`oceanbase/powermem-server:latest`。
@@ -226,7 +250,7 @@ Docker / Compose 部署见 [API Server](docs/api/0005-api_server.md) 与 [Docker
 | LLM | Anthropic、OpenAI、Azure OpenAI、Gemini、Qwen（+ ASR 语音）、DeepSeek、Ollama、vLLM、SiliconFlow、Z.AI、LangChain 包装层 |
 | Embedding | OpenAI、Azure OpenAI、Qwen（+ VL 多模态、稀疏向量）、Gemini、Vertex AI、AWS Bedrock、Ollama、LM Studio、HuggingFace、Together、SiliconFlow、Z.AI、OceanBase MASS、LangChain 包装层 |
 | Rerank | Jina、Qwen、Z.AI、通用接口 |
-| Storage | OceanBase（含图存储）、嵌入式 SeekDB、PostgreSQL/pgvector、SQLite |
+| Storage | OceanBase（含图存储）、嵌入式 seekdb、PostgreSQL/pgvector、SQLite |
 
 ---
 
@@ -239,6 +263,7 @@ Docker / Compose 部署见 [API Server](docs/api/0005-api_server.md) 与 [Docker
 - [CLI 使用指南](docs/guides/0012-cli_usage.md) — `pmem`、交互 Shell、备份与迁移
 - [多智能体](docs/guides/0005-multi_agent.md) — 作用域、隔离与跨智能体共享
 - [集成说明](docs/guides/0009-integrations.md) — LangChain 等框架接入
+- [生态集成](docs/integrations/overview.md) — AI 客户端与 IDE（[Claude Code](docs/integrations/claude_code.md) 等）
 - [Docker 与部署](docker/README.md) — 镜像、Compose、运行 API 服务
 - [开发说明](docs/development/overview.md) — 本地开发、测试与贡献
 
@@ -254,7 +279,7 @@ Docker / Compose 部署见 [API Server](docs/api/0005-api_server.md) 与 [Docker
 | 版本 | 日期 | 说明 |
 |------|------|------|
 | 1.2.0 | 2026-04 | Experience + Skill 双层蒸馏与 `distill_all()`（自进化记忆，AppWorld +15 pts）；OB MASS Embedding；Qwen VL 多模态 Embedding；OceanBase Zero Mode 兼容；LOCOMO 准确率提升至 87.79% |
-| 1.1.0 | 2026-04-02 | OceanBase 存储支持嵌入式 SeekDB，无需单独部署数据库服务；[IDE 集成](apps/README.md)（VS Code 扩展、Claude Code 插件） |
+| 1.1.0 | 2026-04-02 | OceanBase 存储支持嵌入式 seekdb，无需单独部署数据库服务；[IDE 集成](apps/README.md)（VS Code 扩展、Claude Code 插件） |
 | 1.0.0 | 2026-03-16 | CLI（`pmem`）：记忆操作、配置、备份/恢复/迁移、交互 Shell、补全；Web Dashboard |
 | 0.5.0 | 2026-02-06 | SDK/API 统一配置（pydantic-settings）；OceanBase 原生混合检索；记忆查询与列表排序；用户画像输出语言定制 |
 | 0.4.0 | 2026-01-20 | 稀疏向量混合检索；基于画像的查询改写；表结构升级与迁移工具 |