diff --git a/README.md b/README.md index 57a9d536a9..57a6caf8a2 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ *[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)* -[Website](https://powercontext.oceanbase.io/) · [Quickstart](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) · [Integrations](https://powercontext.oceanbase.io/en/docs/integrations/) · [Benchmarks](https://powercontext.oceanbase.io/en/benchmarks/) · [Interfaces](https://powercontext.oceanbase.io/en/docs/develop/interfaces/) +[Website](https://powercontext.oceanbase.io/) · [Quickstart](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) · [Manual startup](docs/en/docs/get-started/manual-start.md) · [Integrations](https://powercontext.oceanbase.io/en/docs/integrations/) · [Benchmarks](https://powercontext.oceanbase.io/en/benchmarks/) · [Interfaces](https://powercontext.oceanbase.io/en/docs/develop/interfaces/) ## What is PowerContext? @@ -147,6 +147,8 @@ scores. Windows support is `experimental`. ## Quick start +If you want to manually configure and start PowerContext, see the [manual startup guide](docs/en/docs/get-started/manual-start.md). + PowerContext keeps durable project context outside any single chat. A first run follows this path: ```text diff --git a/README_CN.md b/README_CN.md index 8ff79e1a1f..118a18ecb7 100644 --- a/README_CN.md +++ b/README_CN.md @@ -9,7 +9,7 @@ *[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)* -[网站](https://powercontext.oceanbase.io/zh/) · [快速开始](https://powercontext.oceanbase.io/zh/docs/get-started/quickstart/) · [接入 Agent](https://powercontext.oceanbase.io/zh/docs/integrations/) · [评测](https://powercontext.oceanbase.io/zh/benchmarks/) · [接口](https://powercontext.oceanbase.io/zh/docs/develop/interfaces/) +[网站](https://powercontext.oceanbase.io/zh/) · [快速开始](https://powercontext.oceanbase.io/zh/docs/get-started/quickstart/) · [手动启动](docs/zh/docs/get-started/manual-start.md) · [接入 Agent](https://powercontext.oceanbase.io/zh/docs/integrations/) · [评测](https://powercontext.oceanbase.io/zh/benchmarks/) · [接口](https://powercontext.oceanbase.io/zh/docs/develop/interfaces/) ## PowerContext 是什么? @@ -116,6 +116,8 @@ Experience 记录一个场景、一次动作、观察到的结果,以及可复 ## 快速开始 +如果希望自己一步一步配置并启动 PowerContext,请查看[手动启动文档](docs/zh/docs/get-started/manual-start.md)。 + PowerContext 把可长期复用的项目上下文放在单次对话之外。一次完整体验可以概括为: ```text diff --git a/README_JP.md b/README_JP.md index 0478b2300b..34d8702c3c 100644 --- a/README_JP.md +++ b/README_JP.md @@ -9,7 +9,7 @@ *[English](README.md) · [中文](README_CN.md) · [日本語](README_JP.md)* -[Web サイト](https://powercontext.oceanbase.io/en/) · [クイックスタート](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) · [Agent 連携](https://powercontext.oceanbase.io/en/docs/integrations/) · [ベンチマーク](https://powercontext.oceanbase.io/en/benchmarks/) · [インターフェース](https://powercontext.oceanbase.io/en/docs/develop/interfaces/) +[Web サイト](https://powercontext.oceanbase.io/en/) · [クイックスタート](https://powercontext.oceanbase.io/en/docs/get-started/quickstart/) · [手動起動](docs/en/docs/get-started/manual-start.md) · [Agent 連携](https://powercontext.oceanbase.io/en/docs/integrations/) · [ベンチマーク](https://powercontext.oceanbase.io/en/benchmarks/) · [インターフェース](https://powercontext.oceanbase.io/en/docs/develop/interfaces/) ## PowerContext とは何か? @@ -112,6 +112,8 @@ Experience は、状況・行動・観察された結果・再利用可能な教 ## クイックスタート +設定ウィザードを使わずに手動で設定・起動する場合は、[手動起動ガイド](docs/en/docs/get-started/manual-start.md)を参照してください。 + PowerContext は、長く使うプロジェクトのコンテキストを 1 つの会話の外に保持します。最初の実行は次の流れです。 ```text diff --git a/docs/en/docs/get-started/manual-start.md b/docs/en/docs/get-started/manual-start.md new file mode 100644 index 0000000000..435f93385a --- /dev/null +++ b/docs/en/docs/get-started/manual-start.md @@ -0,0 +1,280 @@ +--- +title: Manually start PowerContext +description: Configure and start the PowerContext Server manually without the setup wizard, connect Codex, and verify Memory. +--- + +# Manually start PowerContext + +This page explains how to configure and start the PowerContext Server without using the powercontext config init setup wizard, then bind Codex to a Scope. + +This guide applies to macOS and Linux only. It uses POSIX shell syntax such as `source`, `env -i`, and here-documents; Windows PowerShell is not covered by this guide. + +Use this page if you want to understand each step, troubleshoot configuration, or control the Server address, port, Dashboard, and authentication yourself. If you prefer the interactive setup wizard, see [Quick Start](quickstart.md). + +## Manual startup versus Quick Start + +Quick Start uses the setup wizard: + +```text +config init → generate .env → start Server → create Scope → connect Agent +``` + +Manual startup does not run config init. You prepare the environment variables or configuration file yourself: + +```text +write configuration → validate → server run → check Server → create Scope → bind Agent +``` + +Manual startup does not mean compiling PowerContext from source. It means running PowerContext without relying on the configuration wizard and choosing the Server settings yourself. + +## Prerequisites + +You need Python 3.11 or newer, Git, [uv](https://docs.astral.sh/uv/getting-started/installation/), and an Agent CLI such as Codex CLI if you want to connect an Agent. + +```bash +python3 --version +git --version +uv --version +``` + +## 1. Install PowerContext + +If uv is not installed, run: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +source "$HOME/.local/bin/env" +``` + +Install the PowerContext CLI and local Server: + +```bash +uv tool install --force "powercontext[cli,server]==1.3.0" +powercontext --version +powercontext --help +``` + +## 2. Stop a possibly running personal service + +If you previously ran powercontext service install, a personal background Server may already be running. It may occupy the default port and make it unclear which Server you are checking. + +```bash +powercontext service status +``` + +If the personal service is running, stop it: + +```bash +powercontext service stop +``` + +This stops the personal service and prevents automatic activation while keeping its configuration and data. + +## 3. Create a manual configuration file + +```bash +mkdir -p ~/powercontext-manual +cd ~/powercontext-manual +nano manual.env +``` + +Put the following values in manual.env: + +```dotenv +POWERCONTEXT_SERVER_HTTP_HOST=127.0.0.1 +POWERCONTEXT_SERVER_HTTP_PORT=18080 +POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true +POWERCONTEXT_SERVER_ACCESS_MODE=disabled +``` + +The settings mean: + +| Setting | Purpose | +| --- | --- | +| POWERCONTEXT_SERVER_HTTP_HOST | Listen only on the local machine | +| POWERCONTEXT_SERVER_HTTP_PORT | Listen on port 18080 | +| POWERCONTEXT_SERVER_DASHBOARD_ENABLED | Enable the Dashboard | +| POWERCONTEXT_SERVER_ACCESS_MODE | Disable authentication for local testing | + +This configuration does not specify a database or models, so it uses the default SQLite database and does not enable inference capabilities. + +## 4. Validate the manual configuration + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + powercontext config validate \ + --env-file ~/powercontext-manual/manual.env +``` + +A successful command prints Configuration is valid. This step only validates the configuration; it does not start the Server. + +## 5. Start the Server manually + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + powercontext server run \ + --env-file ~/powercontext-manual/manual.env +``` + +Keep this terminal open. A successful startup looks similar to: + +```text +PowerContext Server is ready +Uvicorn running on http://127.0.0.1:18080 +``` + +Press Ctrl-C to stop the foreground Server. If Generation and Embedding models are not configured, PowerContext prints a notice, but explicit Basic Memory saves and recall still work. + +## 6. Open the Dashboard + +Open the following address in a browser: + +```text +http://127.0.0.1:18080/dashboard/home +``` + +Authentication is disabled, so the page can be opened directly from the local machine. An empty Dashboard on the first visit is expected. + +## 7. Check the Server + +Keep the Server running and open another terminal: + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \ + powercontext doctor +``` + +Continue with: + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \ + powercontext ready +``` + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \ + powercontext capabilities +``` + +Expected output includes: + +```text +server liveness: ok - http://127.0.0.1:18080 +server readiness: ok - http://127.0.0.1:18080 +access_mode: disabled +database: ready +``` + +doctor checks the installation, Server liveness, and readiness. ready checks whether the Server can provide requests. capabilities shows the currently enabled capabilities. + +## 8. Create a Scope manually + +A Scope is an isolated space for project context. It separates Sources, Memory, Topic Memory, Handoffs, and Agent recall data. + +Use the Python Client to call the Server and create a Scope manually. Keep the Server running and execute the following in another terminal: + +```bash +cd ~/powercontext-manual +POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \ +uv run --with "powercontext[client]==1.3.0" python - <<'PY' +import asyncio +import os +from powercontext.client import PowerContextClient +from powercontext.http import CreateScopeRequest + +async def main(): + async with PowerContextClient(os.environ["POWERCONTEXT_CLIENT_SERVER_URL"]) as client: + scope = await client.create_scope( + CreateScopeRequest( + title="manual-powercontext-demo", + summary="Scope created during manual setup", + idempotency_key="manual-powercontext-demo-v1", + ) + ) + print("scope_id:", scope.scope_id) + +asyncio.run(main()) +PY +``` + +The Server returns the real scope_id. Use this ID when binding the Agent; do not construct an ID from the Scope title. + +## 9. Bind the Codex Agent + +Set the real Scope ID in the current terminal: + +```bash +export POWERCONTEXT_CODEX_SCOPE_ID=replace-with-the-scope-id-returned-by-the-server +``` + +Install the Codex plugin matching the Server version and point it to the manually started Server: + +```bash +powercontext setup codex \ + --ref powercontext-v1.3.0 \ + --server-url http://127.0.0.1:18080 +powercontext doctor codex +``` + +The checks should confirm that the plugin, MCP, and tool discovery are working. Installing the plugin does not start the Server, so the Server terminal must remain open. + +## 10. Verify explicit Memory and cross-session recall + +Start a new Codex session from a terminal where POWERCONTEXT_CODEX_SCOPE_ID is set: + +```bash +codex +``` + +Send a message that explicitly asks Codex to save a decision: + +```text +Please save the following decision to PowerContext: + +The Aurora project uses uv to manage Python dependencies and .env for configuration. The first phase will be deployed on a Linux server. +``` + +Exit Codex, start a new session with the same Scope, and ask: + +```text +Please retrieve the Aurora project's dependency management and deployment decision from PowerContext. +``` + +If the Agent retrieves the same content and shows the Memory as active with its source and revision, manual startup, Scope binding, explicit saving, and cross-session recall have all been verified. + +## Capability boundaries + +This page does not configure Generation or Embedding models. It therefore verifies explicit Memory, full-text search, and cross-session recall, but it does not verify automatic Memory extraction or automatic generation of Topic Memory, Experience, or Skill. To enable those capabilities, see [Configure models](configure-models.md). + +## Troubleshooting + +### capabilities shows extraction disabled + +This means that Generation and Embedding models are not configured. It does not prevent explicit Basic Memory saves and recall. + +### capabilities returns 401 + +The Server is usually enforcing authentication while the client has no Token. Confirm that manual.env contains POWERCONTEXT_SERVER_ACCESS_MODE=disabled and use env -i to avoid inheriting old environment variables. + +### The check connects to port 8000 instead of 18080 + +Set the client address explicitly: + +```bash +POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 powercontext ready +``` + +### The Dashboard has no data + +An empty Dashboard on the first visit is expected. Write a Source or Memory through an Agent or API, and confirm that the Dashboard and Agent use the same Server and Scope. + +## Related documentation + +- [Quick Start](quickstart.md): use the setup wizard for a complete memory walkthrough; +- [Configure the Server environment](configure-server-environment.md): learn about configuration files and environment variables; +- [Configure models](configure-models.md): enable automatic extraction and vector retrieval; +- [Deploy the Server](../operate/deploy-server.md): run a personal background service or remote Server; +- [Troubleshoot](../operate/troubleshoot.md): investigate Server, model, and connection issues. diff --git a/docs/en/docs/get-started/meta.json b/docs/en/docs/get-started/meta.json index 2eecee375d..443e11093d 100644 --- a/docs/en/docs/get-started/meta.json +++ b/docs/en/docs/get-started/meta.json @@ -2,6 +2,7 @@ "title": "Get started", "pages": [ "quickstart", + "manual-start", "install-and-run", "configure-server-environment", "configure-models", diff --git a/docs/zh/docs/get-started/manual-start.md b/docs/zh/docs/get-started/manual-start.md new file mode 100644 index 0000000000..1f8cd96f42 --- /dev/null +++ b/docs/zh/docs/get-started/manual-start.md @@ -0,0 +1,280 @@ +--- +title: 手动启动 PowerContext +description: 不使用配置向导,手动配置并启动 PowerContext Server,连接 Codex 并验证 Memory。 +--- + +# 手动启动 PowerContext + +本页介绍不使用 powercontext config init 配置向导时,如何手动配置和启动 PowerContext Server,并将 Codex 绑定到一个 Scope。 + +本指南仅适用于 macOS 和 Linux。文中的命令使用 POSIX Shell 语法,例如 `source`、`env -i` 和 here-document;本文不提供 Windows PowerShell 流程。 + +本页适合希望了解每一步、排查配置问题,或需要自己控制 Server 地址、端口、Dashboard 和认证方式的用户。如果希望使用交互式配置向导快速完成安装,请看[快速开始](quickstart.md)。 + +## 手动启动和快速启动的区别 + +快速启动使用配置向导: + +```text +config init → 生成 .env → 启动 Server → 创建 Scope → 连接 Agent +``` + +手动启动不运行 config init,而是自己准备环境变量或配置文件: + +```text +手动写配置 → validate → server run → 检查 Server → 创建 Scope → 绑定 Agent +``` + +手动启动不是从源码编译 PowerContext,而是不依赖配置向导,自己决定 Server 的运行参数。 + +## 前置条件 + +需要 Python 3.11 或更高版本、Git、[uv](https://docs.astral.sh/uv/getting-started/installation/),以及要连接的 Agent CLI(例如 Codex CLI)。 + +```bash +python3 --version +git --version +uv --version +``` + +## 1. 安装 PowerContext + +如果尚未安装 uv,可以先执行: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +source "$HOME/.local/bin/env" +``` + +安装 PowerContext CLI 和本地 Server: + +```bash +uv tool install --force "powercontext[cli,server]==1.3.0" +powercontext --version +powercontext --help +``` + +## 2. 停止可能正在运行的个人服务 + +如果之前使用过 powercontext service install,系统中可能已有个人后台 Server。它可能占用默认端口,导致你误以为检查的是手动启动的 Server。 + +```bash +powercontext service status +``` + +如果个人服务正在运行,停止它: + +```bash +powercontext service stop +``` + +这个命令会停止个人服务并禁止它自动启动,但会保留服务配置和数据。 + +## 3. 创建手动配置文件 + +```bash +mkdir -p ~/powercontext-manual +cd ~/powercontext-manual +nano manual.env +``` + +在 manual.env 中写入: + +```dotenv +POWERCONTEXT_SERVER_HTTP_HOST=127.0.0.1 +POWERCONTEXT_SERVER_HTTP_PORT=18080 +POWERCONTEXT_SERVER_DASHBOARD_ENABLED=true +POWERCONTEXT_SERVER_ACCESS_MODE=disabled +``` + +配置项作用: + +| 配置项 | 作用 | +| --- | --- | +| POWERCONTEXT_SERVER_HTTP_HOST | 只监听本机地址 | +| POWERCONTEXT_SERVER_HTTP_PORT | 监听 18080 端口 | +| POWERCONTEXT_SERVER_DASHBOARD_ENABLED | 开启 Dashboard | +| POWERCONTEXT_SERVER_ACCESS_MODE | 关闭本机测试所需的认证 | + +本配置没有指定数据库和模型,因此使用默认 SQLite,并且不启用模型推理能力。 + +## 4. 验证手动配置 + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + powercontext config validate \ + --env-file ~/powercontext-manual/manual.env +``` + +成功时会显示 Configuration is valid。这一步只验证配置,不会启动 Server。 + +## 5. 手动启动 Server + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + powercontext server run \ + --env-file ~/powercontext-manual/manual.env +``` + +保持这个终端运行。成功启动时会看到类似日志: + +```text +PowerContext Server is ready +Uvicorn running on http://127.0.0.1:18080 +``` + +按 Ctrl-C 可以停止前台 Server。没有配置 Generation 和 Embedding 模型时会出现提示,但不影响基础 Memory 的显式保存和召回。 + +## 6. 访问 Dashboard + +在浏览器打开: + +```text +http://127.0.0.1:18080/dashboard/home +``` + +认证已关闭,因此本机可以直接访问。第一次打开页面没有数据是正常的。 + +## 7. 检查 Server + +保持 Server 运行,另开终端执行: + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \ + powercontext doctor +``` + +继续检查: + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \ + powercontext ready +``` + +```bash +env -i HOME="$HOME" PATH="$PATH" LANG=C.UTF-8 \ + POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \ + powercontext capabilities +``` + +预期结果包括: + +```text +server liveness: ok - http://127.0.0.1:18080 +server readiness: ok - http://127.0.0.1:18080 +access_mode: disabled +database: ready +``` + +doctor 检查安装、Server 存活和就绪状态;ready 检查服务是否可以提供请求;capabilities 显示当前能力。 + +## 8. 手动创建 Scope + +Scope 是项目上下文数据的隔离空间,用于隔离 Source、Memory、Topic Memory、Handoff 和 Agent 召回数据。 + +使用 Python Client 手动调用 Server 创建 Scope。保持 Server 运行,在另一个终端执行: + +```bash +cd ~/powercontext-manual +POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 \ +uv run --with "powercontext[client]==1.3.0" python - <<'PY' +import asyncio +import os +from powercontext.client import PowerContextClient +from powercontext.http import CreateScopeRequest + +async def main(): + async with PowerContextClient(os.environ["POWERCONTEXT_CLIENT_SERVER_URL"]) as client: + scope = await client.create_scope( + CreateScopeRequest( + title="manual-powercontext-demo", + summary="Scope created during manual setup", + idempotency_key="manual-powercontext-demo-v1", + ) + ) + print("scope_id:", scope.scope_id) + +asyncio.run(main()) +PY +``` + +Server 会返回真实的 scope_id。后续绑定 Agent 时必须使用这个 ID,不能根据 Scope 标题自行拼接。 + +## 9. 绑定 Codex Agent + +将真实 Scope ID 设置到当前终端: + +```bash +export POWERCONTEXT_CODEX_SCOPE_ID=替换为Server返回的真实scope_id +``` + +安装与 Server 版本匹配的 Codex 插件,并指定手动启动的 Server: + +```bash +powercontext setup codex \ + --ref powercontext-v1.3.0 \ + --server-url http://127.0.0.1:18080 +powercontext doctor codex +``` + +成功时应看到插件、MCP 和工具发现检查通过。安装插件不会启动 Server,因此 Server 终端必须保持运行。 + +## 10. 验证显式 Memory 和跨会话召回 + +从设置了 POWERCONTEXT_CODEX_SCOPE_ID 的终端启动新的 Codex: + +```bash +codex +``` + +发送一条明确要求保存的消息: + +```text +请把下面这条决定保存到 PowerContext: + +Aurora 项目使用 uv 管理 Python 依赖,配置文件使用 .env;第一阶段部署在 Linux 服务器上。 +``` + +退出 Codex 后,在相同 Scope 下重新启动新会话,并询问: + +```text +请从 PowerContext 找回 Aurora 项目的依赖管理和部署决定。 +``` + +如果 Agent 找回相同内容,并显示 Memory 的 active 状态、来源和 revision,说明手动启动、Scope 绑定、显式保存和跨会话召回都验证成功。 + +## 能力边界 + +本页没有配置 Generation 和 Embedding 模型,因此可以验证显式 Memory、全文搜索和跨会话召回,但不能期待自动 Memory 提取、Topic Memory、Experience 或 Skill 自动生成。需要这些能力时,请参考[模型配置](configure-models.md)。 + +## 常见问题 + +### capabilities 显示 extraction disabled + +这是因为没有配置 Generation 和 Embedding 模型,不影响基础 Memory 的显式保存与召回。 + +### capabilities 返回 401 + +通常是 Server 开启了认证但客户端没有 Token。确认 manual.env 中的 POWERCONTEXT_SERVER_ACCESS_MODE=disabled,并使用 env -i 避免继承旧环境变量。 + +### 检查到了 8000 而不是 18080 + +检查时显式设置客户端地址: + +```bash +POWERCONTEXT_CLIENT_SERVER_URL=http://127.0.0.1:18080 powercontext ready +``` + +### Dashboard 没有数据 + +首次打开没有数据是正常的。需要先通过 Agent 或 API 写入 Source 或 Memory,并确认 Dashboard 和 Agent 使用同一个 Server 和 Scope。 + +## 相关文档 + +- [快速开始](quickstart.md):使用配置向导完成完整记忆体验; +- [配置 Server 环境](configure-server-environment.md):了解配置文件和环境变量; +- [配置模型](configure-models.md):启用自动提取和向量检索; +- [部署 Server](../operate/deploy-server.md):运行个人后台服务和远程 Server; +- [故障排查](../operate/troubleshoot.md):排查 Server、模型和连接问题。 diff --git a/docs/zh/docs/get-started/meta.json b/docs/zh/docs/get-started/meta.json index 029dbe2848..b597080721 100644 --- a/docs/zh/docs/get-started/meta.json +++ b/docs/zh/docs/get-started/meta.json @@ -2,6 +2,7 @@ "title": "开始使用", "pages": [ "quickstart", + "manual-start", "install-and-run", "configure-server-environment", "configure-models",