From 3dc354a1ebacd1c3cc510614ef89de2136c904c7 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 25 Mar 2026 18:13:29 +0800 Subject: [PATCH 1/6] docs: rewrite readme to make it clear Signed-off-by: Chojan Shang --- README.md | 211 +++++++++++++++++++++----------------------------- README_CN.md | 213 +++++++++++++++++++++------------------------------ README_JP.md | 209 ++++++++++++++++++++------------------------------ 3 files changed, 257 insertions(+), 376 deletions(-) diff --git a/README.md b/README.md index 124281a..7eb09c4 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,6 @@

-

- -*PowerMem integrated with [OpenClaw](https://github.com/openclaw-ai/openclaw): intelligent memory for AI agents. **OpenClaw PowerMem Plugin**: [View Plugin](https://github.com/ob-labs/memory-powermem)* - -One command to add PowerMem memory to OpenClaw: `openclaw plugins install memory-powermem`. - -PowerMem with OpenClaw - -

-

PowerMem PyPI - Downloads @@ -40,7 +30,13 @@ One command to add PowerMem memory to OpenClaw: `openclaw plugins install memory [English](README.md) | [中文](README_CN.md) | [日本語](README_JP.md) -## ✨ Highlights +# PowerMem — Intelligent Memory for AI Applications + +**PowerMem** is long-term memory infrastructure for AI apps: **hybrid vector + full-text + graph** retrieval, **Ebbinghaus-style forgetting**, and **LLM-driven memory extraction**, with **multi-agent isolation/sharing**, **user profiles**, and **multimodal** inputs (text, image, audio). The same feature set is available via **Python SDK**, **CLI (`pmem`)**, **HTTP API Server (with Dashboard)**, and **MCP Server**, all sharing **one `.env` configuration**. + +> **News:** [OpenClaw](https://github.com/openclaw-ai/openclaw) can use PowerMem as long-term memory via [`memory-powermem`](https://github.com/ob-labs/memory-powermem) (`openclaw plugins install memory-powermem`). + +## Why PowerMem

@@ -48,100 +44,95 @@ One command to add PowerMem memory to OpenClaw: `openclaw plugins install memory
-- 🎯 **Accurate**: **[48.77% Accuracy Improvement]** More accurate than full-context in the LOCOMO benchmark (78.70% VS 52.9%) -- ⚡ **Agile**: **[91.83% Faster Response]** Significantly reduced p95 latency for retrieval compared to full-context (1.44s VS 17.12s) -- 💰 **Affordable**: **[96.53% Token Reduction]** Significantly reduced costs compared to full-context without sacrificing performance (0.9k VS 26k) +On the [LOCOMO](https://github.com/snap-research/locomo) benchmark vs. stuffing full conversation context: -# 🧠 PowerMem - Intelligent Memory System +- **More accurate**: ~**48.77%** relative accuracy gain (78.70% vs. 52.9%) +- **Lower latency**: retrieval **p95** ~**1.44s** vs. **17.12s** (~**91.83%** faster) +- **Fewer tokens**: ~**0.9k** vs. **26k** (~**96.53%** reduction) without sacrificing the above -In AI application development, enabling large language models to persistently "remember" historical conversations, user preferences, and contextual information is a core challenge. PowerMem combines a hybrid storage architecture of vector retrieval, full-text search, and graph databases, and introduces the Ebbinghaus forgetting curve theory from cognitive science to build a powerful memory infrastructure for AI applications. The system also provides comprehensive multi-agent support capabilities, including agent memory isolation, cross-agent collaboration and sharing, fine-grained permission control, and privacy protection mechanisms, enabling multiple AI agents to achieve efficient collaboration while maintaining independent memory spaces. +## Core Features -## 🚀 Core Features +### Developer-friendly -### 👨‍💻 Developer Friendly -- 🔌 **[Lightweight Integration](docs/examples/scenario_1_basic_usage.md)**: Provides a simple Python SDK, automatically loads configuration from `.env` files, enabling developers to quickly integrate into existing projects. Also supports [CLI](docs/guides/0012-cli_usage.md) (`pmem`), [MCP Server](docs/api/0004-mcp.md), and [HTTP API Server](docs/api/0005-api_server.md) integration methods +- **[Lightweight integration](docs/examples/scenario_1_basic_usage.md)**: Python SDK with `.env` auto-loading; also [CLI](docs/guides/0012-cli_usage.md) (`pmem`), [MCP Server](docs/api/0004-mcp.md), and [HTTP API Server](docs/api/0005-api_server.md) -### 🧠 Intelligent Memory Management -- 🔍 **[Intelligent Memory Extraction](docs/examples/scenario_2_intelligent_memory.md)**: Automatically extracts key facts from conversations through LLM, intelligently detects duplicates, updates conflicting information, and merges related memories to ensure accuracy and consistency of the memory database -- 📉 **[Ebbinghaus Forgetting Curve](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)**: Based on the memory forgetting patterns from cognitive science, automatically calculates memory retention rates and implements time-decay weighting, prioritizing recent and relevant memories, allowing AI systems to naturally "forget" outdated information like humans +### Intelligent memory management -### 👤 User Profile Support -- 🎭 **[User Profile](docs/examples/scenario_9_user_memory.md)**: Automatically builds and updates user profiles based on historical conversations and behavioral data, applicable to scenarios such as personalized recommendations and AI companionship, enabling AI systems to better understand and serve each user +- **[Smart extraction](docs/examples/scenario_2_intelligent_memory.md)**: LLM-based fact extraction, deduplication, conflict resolution, and merging +- **[Ebbinghaus forgetting curve](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)**: time- and relevance-aware decay; prioritize recent, useful memories -### 🤖 Multi-Agent Support -- 🔐 **[Agent Shared/Isolated Memory](docs/examples/scenario_3_multi_agent.md)**: Provides independent memory spaces for each agent, supports cross-agent memory sharing and collaboration, and enables flexible permission management through scope control +### User profiles -### 🎨 Multimodal Support -- 🖼️ **[Text, Image, and Audio Memory](docs/examples/scenario_7_multimodal.md)**: Automatically converts images and audio to text descriptions for storage, supports retrieval of multimodal mixed content (text + image + audio), enabling AI systems to understand richer contextual information +- **[User profile](docs/examples/scenario_9_user_memory.md)**: profiles from history and behavior—personalization, companions, and similar use cases -### 💾 Deeply Optimized Data Storage -- 📦 **[Sub Stores Support](docs/examples/scenario_6_sub_stores.md)**: Implements data partition management through sub stores, supports automatic query routing, significantly improving query performance and resource utilization for ultra-large-scale data -- 🔗 **[Hybrid Retrieval](docs/examples/scenario_2_intelligent_memory.md)**: Combines multi-channel recall capabilities of vector retrieval, full-text search, and graph retrieval, builds knowledge graphs through LLM and supports multi-hop graph traversal for precise retrieval of complex memory relationships +### Multi-agent -## 🚀 Quick Start +- **[Shared / isolated memory](docs/examples/scenario_3_multi_agent.md)**: per-agent spaces, cross-agent collaboration, scope-based permissions -### 📥 Installation +### Multimodal + +- **[Text, image, audio](docs/examples/scenario_7_multimodal.md)**: media summarized to text for storage and mixed retrieval + +### Storage & retrieval + +- **[Sub stores](docs/examples/scenario_6_sub_stores.md)**: partitioning and automatic routing for very large corpora +- **[Hybrid retrieval](docs/examples/scenario_2_intelligent_memory.md)**: vector + full-text + graph (multi-hop), with LLM-assisted graph construction + +## Quick Start + +Below: **Install** → **Python SDK** → **CLI (`pmem`)** → **HTTP API & Dashboard** → **MCP**. Options: [.env.example](.env.example) and the [configuration guide](docs/guides/0003-configuration.md). + +### Install ```bash pip install powermem ``` -### 💡 Basic Usage(SDK) - -**✨ Simplest Way**: Create memory from `.env` file automatically! [Configuration Reference](.env.example) +### Basic usage (SDK) ```python from powermem import Memory, auto_config -# Load configuration (auto-loads from .env) config = auto_config() -# Create memory instance memory = Memory(config=config) -# Add memory memory.add("User likes coffee", user_id="user123") -# Search memories results = memory.search("user preferences", user_id="user123") for result in results.get('results', []): print(f"- {result.get('memory')}") ``` -For more detailed examples and usage patterns, see the [Getting Started Guide](docs/guides/0001-getting_started.md). +More patterns: [Getting Started](docs/guides/0001-getting_started.md). -### ⌨️ PowerMem CLI (1.0.0+) +### PowerMem CLI (1.0.0+) -PowerMem provides a command-line interface (`pmem`) for memory operations, configuration, backup/restore, and an interactive shell—without writing Python code. +`pmem` covers memory CRUD, config, backup/restore, and an interactive shell. ```bash -# Add and search memories pmem memory add "User prefers dark mode" --user-id user123 pmem memory search "preferences" --user-id user123 -# Configuration and statistics pmem config show -pmem config init # Interactive .env wizard +pmem config init pmem stats --json -# Interactive shell pmem shell ``` -For full CLI reference and examples, see the [CLI Usage Guide](docs/guides/0012-cli_usage.md). - -### 🌐 HTTP API Server & Dashboard - -PowerMem provides a production-ready HTTP API server that exposes all core memory management capabilities through RESTful APIs. It also serves a **Dashboard** (at `/dashboard/`) as the web admin UI. +Full reference: [CLI usage](docs/guides/0012-cli_usage.md). -**Relationship with SDK**: The API server uses the same PowerMem SDK under the hood and shares the same configuration (`.env` file). It provides an HTTP interface to the same memory management features available in the Python SDK, making PowerMem accessible to non-Python applications. +### HTTP API Server & Dashboard -**Starting the API Server (with Dashboard)**: +Uses the **same** PowerMem SDK and `.env` as your code. Exposes REST, a **`/dashboard/`** UI, and **`/docs`** (OpenAPI). ```bash -# Method 1: Using CLI command (after pip install) powermem-server --host 0.0.0.0 --port 8000 +``` + +Docker & Compose: -# Method 2: Using Docker (API server + dashboard in one container) +```bash docker run -d \ --name powermem-server \ -p 8000:8000 \ @@ -149,61 +140,27 @@ docker run -d \ --env-file .env \ oceanbase/powermem-server:latest -# Or use Docker Compose (recommended) docker-compose -f docker/docker-compose.yml up -d ``` -Once started, the same server provides: -- RESTful API endpoints for all memory operations -- **Dashboard** at `http://localhost:8000/dashboard/` -- Interactive API documentation at `http://localhost:8000/docs` -- API Key authentication and rate limiting support -- Same configuration as SDK (via `.env` file) - -For complete API documentation and usage examples, see the [API Server Documentation](docs/api/0005-api_server.md). - -### 🔌 MCP Server +Details: [API Server](docs/api/0005-api_server.md). -PowerMem also provides a Model Context Protocol (MCP) server that enables integration with MCP-compatible clients such as Claude Desktop. The MCP server exposes PowerMem's memory management capabilities through the MCP protocol, allowing AI assistants to access and manage memories seamlessly. +### MCP Server -**Relationship with SDK**: The MCP server uses the same PowerMem SDK and shares the same configuration (`.env` file). It provides an MCP interface to the same memory management features, making PowerMem accessible to MCP-compatible AI assistants. - -**Installation**: +Same SDK and `.env`; exposes memory tools to MCP clients (e.g. Claude Desktop). ```bash -# Install PowerMem (required) pip install powermem +# Install uv / uvx: https://docs.astral.sh/uv/getting-started/ -# Install uvx (if not already installed) -# On macOS/Linux: -curl -LsSf https://astral.sh/uv/install.sh | sh - -# On Windows: -powershell -c "irm https://astral.sh/uv/install.ps1 | iex" -``` - -**Starting the MCP Server**: - -```bash -# SSE mode (recommended, default port 8000) uvx powermem-mcp sse - -# SSE mode with custom port uvx powermem-mcp sse 8001 - -# Stdio mode uvx powermem-mcp stdio - -# Streamable HTTP mode (default port 8000) uvx powermem-mcp streamable-http - -# Streamable HTTP mode with custom port uvx powermem-mcp streamable-http 8001 ``` -**Integration with Claude Desktop**: - -Add the following configuration to your Claude Desktop config file: +Example Claude Desktop config (SSE): ```json { @@ -215,44 +172,48 @@ Add the following configuration to your Claude Desktop config file: } ``` -The MCP server provides tools for memory management including adding, searching, updating, and deleting memories. For complete MCP documentation and usage examples, see the [MCP Server Documentation](docs/api/0004-mcp.md). +Details: [MCP Server](docs/api/0004-mcp.md). + +## Ecosystem & integrations + +### Examples -## 🔗 Integrations & Demos -- 🔗 **openclaw Memory Plugin**: Use PowerMem as long-term memory in [openclaw](https://github.com/openclaw/openclaw) via extraction, Ebbinghaus forgetting curve, multi-agent isolation. [View Plugin](https://github.com/ob-labs/memory-powermem) -- 🔗 **LangChain Integration**: Build medical support chatbot using LangChain + PowerMem + OceanBase, [View Example](examples/langchain/README.md) -- 🔗 **LangGraph Integration**: Build customer service chatbot using LangGraph + PowerMem + OceanBase, [View Example](examples/langgraph/README.md) +- **LangChain**: [medical support chatbot](examples/langchain/README.md) +- **LangGraph**: [customer service bot](examples/langgraph/README.md) -## 📚 Documentation +## Documentation -- 📖 **[Getting Started](docs/guides/0001-getting_started.md)**: Installation and quick start guide -- ⌨️ **[CLI Usage Guide](docs/guides/0012-cli_usage.md)**: PowerMem CLI (pmem) reference (1.0.0+) -- ⚙️ **[Configuration Guide](docs/guides/0003-configuration.md)**: Complete configuration options -- 🤖 **[Multi-Agent Guide](docs/guides/0005-multi_agent.md)**: Multi-agent scenarios and examples -- 🔌 **[Integrations Guide](docs/guides/0009-integrations.md)**: Integrations Guide -- 📦 **[Sub Stores Guide](docs/guides/0006-sub_stores.md)**: Sub stores usage and examples -- 📋 **[API Documentation](docs/api/overview.md)**: Complete API reference -- 🏗️ **[Architecture Guide](docs/architecture/overview.md)**: System architecture and design -- 📓 **[Examples](docs/examples/overview.md)**: Interactive Jupyter notebooks and use cases -- 👨‍💻 **[Development Documentation](docs/development/overview.md)**: Developer documentation +| Topic | Link | +|------|------| +| Getting started | [Guide](docs/guides/0001-getting_started.md) | +| CLI | [CLI usage](docs/guides/0012-cli_usage.md) | +| Configuration | [Configuration](docs/guides/0003-configuration.md) | +| Multi-agent | [Multi-Agent](docs/guides/0005-multi_agent.md) | +| Integrations | [Integrations](docs/guides/0009-integrations.md) | +| Sub stores | [Sub stores](docs/guides/0006-sub_stores.md) | +| API | [API overview](docs/api/overview.md) | +| Architecture | [Architecture](docs/architecture/overview.md) | +| Examples | [Examples](docs/examples/overview.md) | +| Development | [Development](docs/development/overview.md) | -## ⭐ Highlights Release Notes +## Release highlights -| Version | Release Date | Function | -|---------|--------------|---------| -| 1.0.0 | 2026.03.16 |
  • PowerMem CLI (pmem): memory operations, config management, backup/restore/migrate, interactive shell, and shell completion
  • Web Dashboard for memory management and visualization
| -| 0.5.0 | 2026.02.06 |
  • Unified configuration governance across SDK/API Server (pydantic-settings based)
  • Added OceanBase native hybrid search support
  • Enhanced Memory query handling and added sorting support for memory list operations
  • Added user profile support for custom native-language output
| -| 0.4.0 | 2026.01.20 |
  • Sparse vector support for enhanced hybrid retrieval, combining dense vector, full-text, and sparse vector search
  • User memory query rewriting - automatically enhances search queries based on user profiles for improved recall
  • Schema upgrade and data migration tools for existing tables
| -| 0.3.0 | 2026.01.09 |
  • Production-ready HTTP API Server with RESTful endpoints for all memory operations
  • Docker support for easy deployment and containerization
| -| 0.2.0 | 2025.12.16 |
  • Advanced user profile management, supporting "personalized experience" for AI applications
  • Expanded multimodal support, including text, image, and audio memory
| -| 0.1.0 | 2025.11.14 |
  • Core memory management functionality, supporting persistent storage of memories
  • Hybrid retrieval supporting vector, full-text, and graph search
  • Intelligent memory extraction based on LLM fact extraction
  • Full lifecycle memory management supporting Ebbinghaus forgetting curve
  • Multi-Agent memory management support
  • Multiple storage backend support (OceanBase, PostgreSQL, SQLite)
  • Support for knowledge graph retrieval through multi-hop graph search
| +| Version | Date | Notes | +|---------|------|--------| +| 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 | +| 0.3.0 | 2026-01-09 | Production HTTP API Server; Docker | +| 0.2.0 | 2025-12-16 | Advanced profiles; multimodal (text/image/audio) | +| 0.1.0 | 2025-11-14 | Core memory + hybrid retrieval; LLM extraction; forgetting curve; multi-agent; OceanBase/PostgreSQL/SQLite; graph search | -## 💬 Support +## Support -- 🐛 **Issue Reporting**: [GitHub Issues](https://github.com/oceanbase/powermem/issues) -- 💭 **Discussions**: [GitHub Discussions](https://github.com/oceanbase/powermem/discussions) +- **Issues**: [GitHub Issues](https://github.com/oceanbase/powermem/issues) +- **Discussions**: [GitHub Discussions](https://github.com/oceanbase/powermem/discussions) --- -## 📄 License +## License -This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details. \ No newline at end of file +Apache License 2.0 — see [LICENSE](LICENSE). diff --git a/README_CN.md b/README_CN.md index d733b3e..c0fd124 100644 --- a/README_CN.md +++ b/README_CN.md @@ -4,16 +4,6 @@

-

- -*PowerMem 与 [OpenClaw](https://github.com/openclaw-ai/openclaw) 集成：为 AI 智能体提供智能记忆。**OpenClaw PowerMem 记忆插件**：[查看插件](https://github.com/ob-labs/memory-powermem)* - -一行命令即可为 OpenClaw 接入 PowerMem 记忆：`openclaw plugins install memory-powermem`。 - -PowerMem 与 OpenClaw - -

-

PowerMem PyPI - Downloads @@ -41,7 +31,13 @@ [English](README.md) | [中文](README_CN.md) | [日本語](README_JP.md) -## ✨ 亮点 +# PowerMem — 智能 AI 记忆系统 + +**PowerMem** 是面向 AI 应用的长期记忆基础设施：混合 **向量 / 全文 / 图** 检索，结合 **艾宾浩斯遗忘曲线** 与 **LLM 记忆抽取**，支持 **多智能体隔离与协作**、**用户画像** 与 **多模态**（文本、图像、音频）。同一套能力可通过 **Python SDK**、**CLI（`pmem`）**、**HTTP API Server（含 Dashboard）** 与 **MCP Server** 接入，配置统一（`.env`）。 + +> **动态：** [OpenClaw](https://github.com/openclaw-ai/openclaw) 可通过插件 [memory-powermem](https://github.com/ob-labs/memory-powermem) 使用 PowerMem 作为长期记忆（`openclaw plugins install memory-powermem`）。 + +## 为什么选择 PowerMem

@@ -49,100 +45,95 @@
-- 🎯 **更准**：**[准确率提升 48.77%]** 在 LOCOMO 基准测试中，相比于 full-context 更准确（78.70% VS 52.9%） -- ⚡ **更快**：**[响应速度快 91.83%]** 相比于 full-context，检索的 p95 延迟显著降低（1.44s VS 17.12s） -- 💰 **更省**：**[Token 用量降低 96.53%]** 相比于full-context，在不牺牲性能的前提下显著降低成本（0.9k VS 26k） +在 [LOCOMO](https://github.com/snap-research/locomo) 基准上相对「全量上下文」方案： -# 🧠 PowerMem - 智能AI记忆系统 +- **更准**：[准确率提升 48.77%]（78.70% VS 52.9%） +- **更快**：[检索 p95 延迟显著降低]（1.44s VS 17.12s，约 91.83%） +- **更省**：[Token 用量显著下降]（约 0.9k VS 26k，约 96.53%） -在 AI 应用开发中，如何让大语言模型持久化地"记住"历史对话、用户偏好和上下文信息是一个核心挑战。PowerMem 融合向量检索、全文检索和图数据库的混合存储架构，并引入认知科学的艾宾浩斯遗忘曲线理论，为 AI 应用构建了强大的记忆基础设施。系统还提供完善的多智能体支持能力，包括智能体记忆隔离、跨智能体协作共享、细粒度权限控制和隐私保护机制，让多个 AI 智能体能够在保持独立记忆空间的同时实现高效协作。 +## 核心特性 -## 🚀 核心特性 +### 开发者友好 -### 👨‍💻 开发者友好 -- 🔌 **[轻量级接入方式](docs/examples/scenario_1_basic_usage.md)**：提供简洁的 Python SDK 支持，自动从 `.env` 文件加载配置，让开发者快速集成到现有项目中。还支持 [CLI](docs/guides/0012-cli_usage.md)（`pmem`）、[MCP Server](docs/api/0004-mcp.md) 和 [HTTP API Server](docs/api/0005-api_server.md) 三种接入方式 +- **[轻量级接入](docs/examples/scenario_1_basic_usage.md)**：Python SDK 自动从 `.env` 加载配置；另支持 [CLI](docs/guides/0012-cli_usage.md)（`pmem`）、[MCP Server](docs/api/0004-mcp.md)、[HTTP API Server](docs/api/0005-api_server.md) -### 🧠 智能记忆管理 -- 🔍 **[记忆的智能提取](docs/examples/scenario_2_intelligent_memory.md)**：通过 LLM 自动从对话中提取关键事实，智能检测重复、更新冲突信息并合并相关记忆，确保记忆库的准确性和一致性 -- 📉 **[艾宾浩斯遗忘曲线](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)**：基于认知科学的记忆遗忘规律，自动计算记忆保留率并实现时间衰减加权，优先返回最近且相关的记忆，让 AI 系统像人类一样自然"遗忘"过时信息 +### 智能记忆管理 -### 👤 用户画像支持 -- 🎭 **[用户画像](docs/examples/scenario_9_user_memory.md)**：基于用户历史对话和行为数据，自动构建和更新用户画像，适用于个性化推荐、AI 陪伴等场景，让 AI 系统更好地理解和服务每个用户 +- **[智能记忆提取](docs/examples/scenario_2_intelligent_memory.md)**：基于 LLM 抽取事实、去重、消解冲突、合并相关记忆 +- **[艾宾浩斯遗忘曲线](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)**：按时间与相关性衰减，优先返回更近、更相关的记忆 -### 🤖 多智能体支持 -- 🔐 **[智能体共享/隔离记忆](docs/examples/scenario_3_multi_agent.md)**：为每个智能体提供独立的记忆空间，支持跨智能体记忆共享和协作，通过作用域控制实现灵活的权限管理 +### 用户画像 -### 🎨 多模态支持 -- 🖼️ **[文本、图像、语音记忆](docs/examples/scenario_7_multimodal.md)**：自动将图像和音频转换为文本描述并存储，支持多模态混合内容（文本+图像+音频）的检索，让 AI 系统理解更丰富的上下文信息 +- **[用户画像](docs/examples/scenario_9_user_memory.md)**：从对话与行为构建/更新画像，服务个性化推荐、陪伴等场景 -### 💾 深度优化数据存储 -- 📦 **[支持子存储（Sub Stores）](docs/examples/scenario_6_sub_stores.md)**：通过子存储实现数据 -的分区管理，支持自动路由查询，显著提升超大规模数据的查询性能和资源利用率 -- 🔗 **[混合检索](docs/examples/scenario_2_intelligent_memory.md)**：融合向量检索、全文搜索和图检索的多路召回能力，通过 LLM 构建知识图谱并支持多跳图遍历，精准检索复杂的记忆关联关系 +### 多智能体 -## 🚀 快速开始 +- **[共享 / 隔离记忆](docs/examples/scenario_3_multi_agent.md)**：按智能体划分记忆空间，支持跨 Agent 协作与基于作用域的权限控制 -### 📥 安装 +### 多模态 + +- **[文本 / 图像 / 语音](docs/examples/scenario_7_multimodal.md)**：媒体转述后入库，支持图文声混合检索 + +### 存储与检索 + +- **[子存储 Sub Stores](docs/examples/scenario_6_sub_stores.md)**：分区与自动路由，适合超大规模数据 +- **[混合检索](docs/examples/scenario_2_intelligent_memory.md)**：向量 + 全文 + 图（含多跳），并可由 LLM 辅助构图 + +## 快速开始 + +下面按顺序介绍：安装 → **Python SDK** → **CLI（`pmem`）** → **HTTP API 与 Dashboard** → **MCP**。配置见 [.env.example](.env.example) 与 [配置指南](docs/guides/0003-configuration.md)。 + +### 安装 ```bash pip install powermem ``` -### 💡 基本使用（SDK） - -**✨ 最简单的方式**：从 `.env` 文件读取配置自动创建记忆！[配置文件参考](.env.example) +### 基本使用（SDK） ```python from powermem import Memory, auto_config -# 自动从 .env 加载配置并初始化 config = auto_config() memory = Memory(config=config) -# 添加记忆 memory.add("用户喜欢咖啡", user_id="user123") -# 搜索记忆 results = memory.search("用户偏好", user_id="user123") for result in results.get('results', []): print(f"- {result.get('memory')}") ``` -更多详细示例和使用模式，请参阅[入门指南](docs/guides/0001-getting_started.md)。 +更多示例见 [入门指南](docs/guides/0001-getting_started.md)。 -### ⌨️ PowerMem CLI（1.0.0+） +### PowerMem CLI（1.0.0+） -PowerMem 提供命令行工具 `pmem`，无需编写 Python 代码即可进行记忆操作、配置管理、备份/恢复以及交互式 shell。 +`pmem` 支持记忆操作、配置、备份/恢复与交互式 shell。 ```bash -# 添加与搜索记忆 pmem memory add "用户偏好深色模式" --user-id user123 pmem memory search "偏好" --user-id user123 -# 配置与统计 pmem config show -pmem config init # 交互式 .env 配置向导 +pmem config init pmem stats --json -# 交互式 shell pmem shell ``` -完整 CLI 参考与示例请参阅 [CLI 使用指南](docs/guides/0012-cli_usage.md)。 - -### 🌐 HTTP API Server 与 Dashboard - -PowerMem 提供生产就绪的 HTTP API Server，通过 RESTful API 暴露所有核心记忆管理功能。同时提供 **Dashboard**（路径 `/dashboard/`）的 Web 管理界面。 +详见 [CLI 使用指南](docs/guides/0012-cli_usage.md)。 -**与 SDK 的关系**：API Server 底层使用相同的 PowerMem SDK，并共享相同的配置（`.env` 文件）。它提供了与 Python SDK 相同的记忆管理功能的 HTTP 接口，使 PowerMem 可供非 Python 应用程序使用。 +### HTTP API Server 与 Dashboard -**启动 API Server（含 Dashboard）**： +与 SDK **共用**同一套 `.env` 配置；对外提供 REST、`/dashboard/` 管理界面与 `/docs` OpenAPI。 ```bash -# 方法 1：使用 CLI 命令（pip 安装后） powermem-server --host 0.0.0.0 --port 8000 +``` + +Docker 与 Compose 示例： -# 方法 2：使用 Docker（API Server + Dashboard 同一容器） +```bash docker run -d \ --name powermem-server \ -p 8000:8000 \ @@ -150,61 +141,27 @@ docker run -d \ --env-file .env \ oceanbase/powermem-server:latest -# 或使用 Docker Compose（推荐） docker-compose -f docker/docker-compose.yml up -d ``` -启动后，同一服务提供： -- 所有记忆操作的 RESTful API 端点 -- **Dashboard**：访问 `http://localhost:8000/dashboard/` -- 交互式 API 文档，访问 `http://localhost:8000/docs` -- API Key 认证和限流支持 -- 与 SDK 相同的配置（通过 `.env` 文件） - -完整的 API 文档和使用示例，请参阅 [API Server文档](docs/api/0005-api_server.md)。 - -### 🔌 MCP Server +完整说明见 [API Server 文档](docs/api/0005-api_server.md)。 -PowerMem 还提供了模型上下文协议（MCP Server），支持与 Claude Desktop 等 MCP 兼容客户端集成。MCP Server通过 MCP 协议暴露 PowerMem 的记忆管理功能，使 AI 助手能够无缝访问和管理记忆。 +### MCP Server -**与 SDK 的关系**：MCP Server 使用相同的 PowerMem SDK 并共享相同的配置（`.env` 文件）。它提供了与 Python SDK 相同的记忆管理功能的 MCP 接口，使 PowerMem 可供 MCP 兼容的 AI 助手使用。 - -**安装**： +与 SDK **共用**配置；通过 MCP 把记忆能力接到 Claude Desktop 等客户端。 ```bash -# 安装 PowerMem（必需） pip install powermem +# 安装 uv / uvx 见 https://docs.astral.sh/uv/getting-started/ -# 安装 uvx（如果尚未安装） -# 在 macOS/Linux 上： -curl -LsSf https://astral.sh/uv/install.sh | sh - -# 在 Windows 上： -powershell -c "irm https://astral.sh/uv/install.ps1 | iex" -``` - -**启动 MCP Server**： - -```bash -# SSE 模式（推荐，默认端口 8000） -uvx powermem-mcp sse - -# SSE 模式，自定义端口 +uvx powermem-mcp sse # 推荐；默认 8000 uvx powermem-mcp sse 8001 - -# Stdio 模式 uvx powermem-mcp stdio - -# Streamable HTTP 模式（默认端口 8000） uvx powermem-mcp streamable-http - -# Streamable HTTP 模式，自定义端口 uvx powermem-mcp streamable-http 8001 ``` -**与 Claude Desktop 集成**： - -在 Claude Desktop 配置文件中添加以下配置： +Claude Desktop 配置示例（SSE）： ```json { @@ -216,44 +173,48 @@ uvx powermem-mcp streamable-http 8001 } ``` -MCP Server提供记忆管理工具，包括添加、搜索、更新和删除记忆。完整的 MCP 文档和使用示例，请参阅 [MCP Server文档](docs/api/0004-mcp.md)。 +详见 [MCP 文档](docs/api/0004-mcp.md)。 + +## 生态与集成 + +### 示例项目 -## 🔗 集成与演示 -- 🔗 **openclaw 外挂记忆插件**：在 [openclaw](https://github.com/openclaw/openclaw) 中通过插件方式使用 PowerMem 长期记忆，支持智能抽取、艾宾浩斯遗忘曲线、多 Agent 隔离。[查看插件](https://github.com/ob-labs/memory-powermem) -- 🔗 **LangChain 集成**：基于 LangChain + PowerMem + OceanBase 构建医疗支持机器人，[查看示例](examples/langchain/README.md) -- 🔗 **LangGraph 集成**：基于 LangGraph + PowerMem + OceanBase 构建客户服务机器人，[查看示例](examples/langgraph/README.md) +- **LangChain**：[医疗支持机器人示例](examples/langchain/README.md) +- **LangGraph**：[客服机器人示例](examples/langgraph/README.md) -## 📚 文档 +## 文档索引 -- 📖 **[入门指南](docs/guides/0001-getting_started.md)**：安装和快速开始指南 -- ⌨️ **[CLI 使用指南](docs/guides/0012-cli_usage.md)**：PowerMem CLI（pmem）参考（1.0.0+） -- ⚙️ **[配置指南](docs/guides/0003-configuration.md)**：完整的配置选项 -- 🤖 **[多智能体指南](docs/guides/0005-multi_agent.md)**：多智能体场景和示例 -- 🔌 **[集成指南](docs/guides/0009-integrations.md)**：集成指南 -- 📦 **[子存储指南](docs/guides/0006-sub_stores.md)**：子存储的使用方法和示例 -- 📋 **[API 文档](docs/api/overview.md)**：完整的 API 参考 -- 🏗️ **[架构指南](docs/architecture/overview.md)**：系统架构和设计 -- 📓 **[示例](docs/examples/overview.md)**：交互式 Jupyter 笔记本和使用案例 -- 👨‍💻 **[开发者文档](docs/development/overview.md)**：开发者文档 +| 主题 | 链接 | +|------|------| +| 入门 | [Getting Started](docs/guides/0001-getting_started.md) | +| CLI | [CLI 使用指南](docs/guides/0012-cli_usage.md) | +| 配置 | [Configuration](docs/guides/0003-configuration.md) | +| 多智能体 | [Multi-Agent](docs/guides/0005-multi_agent.md) | +| 集成 | [Integrations](docs/guides/0009-integrations.md) | +| 子存储 | [Sub Stores](docs/guides/0006-sub_stores.md) | +| API | [API 总览](docs/api/overview.md) | +| 架构 | [Architecture](docs/architecture/overview.md) | +| 示例 | [Examples](docs/examples/overview.md) | +| 开发 | [Development](docs/development/overview.md) | -## ⭐ 重点发布说明 +## 版本要点 -| Version | Release Date | Function | -|---------|-------|---------| -| 1.0.0 | 2026.03.16 |
  • PowerMem CLI (pmem)：记忆操作、配置管理、备份/恢复/迁移、交互式 shell、shell 补全
  • Web Dashboard：记忆管理与可视化
| -| 0.5.0 | 2026.02.06 |
  • 统一 SDK/API Server 配置治理（基于 pydantic-settings）
  • 新增 OceanBase native hybrid search 支持
  • 增强 Memory 查询处理并支持记忆列表排序
  • 新增用户画像支持自定义原生语言
| -| 0.4.0 | 2026.01.20 |
  • 稀疏向量支持，增强混合检索能力，融合密集向量、全文检索和稀疏向量三种检索方式
  • 用户画像查询改写功能，基于用户画像自动改写查询以提升搜索召回率
  • 表结构升级和数据迁移工具，支持现有表的平滑升级
| -| 0.3.0 | 2026.01.09 |
  • 生产就绪的 HTTP API Server，提供所有记忆操作的 RESTful 接口
  • Docker 支持，便于部署和容器化
    • >
| -| 0.2.0 | 2025.12.16 |
  • 高级用户画像管理，支持 AI 应用的"千人千面"
  • 扩展多模态支持，包括文本、图像和音频记忆
| -| 0.1.0 | 2025.11.14 |
  • 核心记忆管理功能，支持持久化存储记忆
  • 支持向量、全文和图的混合检索
  • 基于 LLM 的事实提取智能记忆
  • 支持基于艾宾浩斯遗忘曲线的全生命周期记忆管理
  • 支持 Multi-Agent 记忆管理
  • 多存储后端支持（OceanBase、PostgreSQL、SQLite）
  • 支持通过多跳图检索的方式处理知识图谱的检索
| +| 版本 | 发布日期 | 说明 | +|------|----------|------| +| 1.0.0 | 2026-03-16 | CLI（`pmem`）：记忆操作、配置、备份/恢复/迁移、交互式 shell、补全；Web Dashboard | +| 0.5.0 | 2026-02-06 | 统一 SDK/API Server 配置（pydantic-settings）；OceanBase native hybrid search；Memory 查询与列表排序增强；用户画像支持自定义输出语言 | +| 0.4.0 | 2026-01-20 | 稀疏向量混合检索；基于用户画像的查询改写；表结构升级与迁移工具 | +| 0.3.0 | 2026-01-09 | 生产级 HTTP API Server；Docker 支持 | +| 0.2.0 | 2025-12-16 | 用户画像增强；多模态（文本/图像/音频） | +| 0.1.0 | 2025-11-14 | 核心记忆与混合检索；LLM 抽取；遗忘曲线；Multi-Agent；OceanBase/PostgreSQL/SQLite；图搜索 | -## 💬 支持 +## 支持 -- 🐛 **问题反馈**：[GitHub Issues](https://github.com/oceanbase/powermem/issues) -- 💭 **讨论交流**：[GitHub Discussions](https://github.com/oceanbase/powermem/discussions) +- **问题反馈**：[GitHub Issues](https://github.com/oceanbase/powermem/issues) +- **讨论**：[GitHub Discussions](https://github.com/oceanbase/powermem/discussions) --- -## 📄 许可证 +## 许可证 -本项目采用 Apache License 2.0 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件。 \ No newline at end of file +本项目采用 **Apache License 2.0**，详见 [LICENSE](LICENSE)。 diff --git a/README_JP.md b/README_JP.md index 21e0cb1..daea405 100644 --- a/README_JP.md +++ b/README_JP.md @@ -4,16 +4,6 @@

-

- -*PowerMem と [OpenClaw](https://github.com/openclaw-ai/openclaw) の連携：AI エージェント向けインテリジェントメモリ。**OpenClaw PowerMem メモリプラグイン**：[プラグインを見る](https://github.com/ob-labs/memory-powermem)* - -1 コマンドで OpenClaw に PowerMem メモリを追加：`openclaw plugins install memory-powermem`。 - -PowerMem と OpenClaw - -

-

PowerMem PyPI - Downloads @@ -40,7 +30,13 @@ [English](README.md) | [中文](README_CN.md) | [日本語](README_JP.md) -## ✨ ハイライト +# PowerMem — AI アプリ向けインテリジェントメモリ + +**PowerMem** は AI アプリケーション向けの長期メモリ基盤です。**ベクトル・全文・グラフ**のハイブリッド検索、**エビングハウス型の忘却**、**LLM によるメモリ抽出**、**マルチエージェント分離/共有**、**ユーザープロフィール**、**マルチモーダル**（テキスト・画像・音声）をサポートします。同一機能を **Python SDK**、**CLI（`pmem`）**、**HTTP API Server（Dashboard 付き）**、**MCP Server** から利用でき、設定は **`.env` で統一**されます。 + +> **ニュース:** [OpenClaw](https://github.com/openclaw-ai/openclaw) はプラグイン [memory-powermem](https://github.com/ob-labs/memory-powermem) により PowerMem を長期メモリとして利用できます（`openclaw plugins install memory-powermem`）。 + +## PowerMem を選ぶ理由

@@ -48,100 +44,95 @@
-- 🎯 **より正確**：**[精度 48.77% 向上]** LOCOMO ベンチマークで full-context より正確（78.70% VS 52.9%） -- ⚡ **より高速**：**[91.83% 高速な応答]** full-context と比較し、検索の p95 遅延が大幅に減少（1.44s VS 17.12s） -- 💰 **より経済的**：**[96.53% トークン削減]** full-context と比較し、性能を犠牲にすることなくコストを大幅に削減（0.9k VS 26k） +[LOCOMO](https://github.com/snap-research/locomo) ベンチマークにおいて、会話全文をコンテキストに載せる方式と比較： + +- **より正確**：精度の相対的な改善（78.70% vs. 52.9%、約 48.77%） +- **より高速**：検索 **p95** が約 **1.44s** vs. **17.12s**（約 91.83% 短縮） +- **トークン削減**：約 **0.9k** vs. **26k**（約 96.53% 削減）を性能を大きく損なわずに実現 + +## 主な機能 + +### 開発者体験 + +- **[軽量統合](docs/examples/scenario_1_basic_usage.md)**：`.env` を読み込む Python SDK に加え、[CLI](docs/guides/0012-cli_usage.md)（`pmem`）、[MCP Server](docs/api/0004-mcp.md)、[HTTP API Server](docs/api/0005-api_server.md) -# 🧠 PowerMem - インテリジェントメモリシステム +### メモリ管理 -AI アプリケーション開発において、大規模言語モデルが履歴会話、ユーザー設定、コンテキスト情報を永続的に「記憶」できるようにすることは、核心的な課題です。PowerMem は、ベクトル検索、全文検索、グラフデータベースのハイブリッドストレージアーキテクチャを組み合わせ、認知科学のエビングハウス忘却曲線理論を導入して、AI アプリケーション向けの強力なメモリインフラストラクチャを構築します。システムは、エージェントメモリの分離、エージェント間のコラボレーションと共有、きめ細かい権限制御、プライバシー保護メカニズムを含む、包括的なマルチエージェントサポート機能も提供し、複数の AI エージェントが独立したメモリ空間を維持しながら効率的なコラボレーションを実現できるようにします。 +- **[スマート抽出](docs/examples/scenario_2_intelligent_memory.md)**：LLM による事実抽出、重複排除、競合解消、マージ +- **[エビングハウス忘却曲線](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)**：時間・関連度に基づく減衰、最近・有用なメモリを優先 -## 🚀 核心機能 +### ユーザープロフィール -### 👨‍💻 開発者フレンドリー -- 🔌 **[軽量級アクセス方式](docs/examples/scenario_1_basic_usage.md)**：シンプルな Python SDK プロトコルサポートを提供し、`.env` ファイルから自動的に設定を読み込み、開発者が既存プロジェクトに迅速に統合できるようにします。また、[CLI](docs/guides/0012-cli_usage.md)（`pmem`）、[MCP サーバー](docs/api/0004-mcp.md)、[HTTP API サーバー](docs/api/0005-api_server.md) の 3 つのアクセス方式をサポートしています +- **[ユーザープロフィール](docs/examples/scenario_9_user_memory.md)**：履歴と行動からプロフィールを構築・更新（パーソナライズ、コンパニオン等） -### 🧠 インテリジェントメモリ管理 -- 🔍 **[メモリのインテリジェント抽出](docs/examples/scenario_2_intelligent_memory.md)**：LLM を通じて会話から重要な事実を自動的に抽出し、重複をインテリジェントに検出し、競合する情報を更新し、関連するメモリをマージして、メモリデータベースの正確性と一貫性を確保します -- 📉 **[エビングハウス忘却曲線](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)**：認知科学の記憶忘却パターンに基づき、メモリ保持率を自動的に計算し、時間減衰重み付けを実装し、最近かつ関連性の高いメモリを優先的に返し、AI システムが人間のように古い情報を自然に「忘却」できるようにします +### マルチエージェント +- **[共有/分離メモリ](docs/examples/scenario_3_multi_agent.md)**：エージェント単位の空間、横断協業、スコープに基づく権限 -### 👤 ユーザープロフィールサポート -- 🎭 **[ユーザープロフィール](docs/examples/scenario_9_user_memory.md)**：ユーザーの履歴会話と行動データに基づいて、ユーザープロフィールを自動的に構築および更新し、パーソナライズされた推奨、AI コンパニオンシップなどのシナリオに適用され、AI システムが各ユーザーをよりよく理解し、サービスを提供できるようにします +### マルチモーダル -### 🤖 マルチエージェントサポート -- 🔐 **[エージェント共有/分離メモリ](docs/examples/scenario_3_multi_agent.md)**：各エージェントに独立したメモリ空間を提供し、エージェント間のメモリ共有とコラボレーションをサポートし、スコープ制御を通じて柔軟な権限管理を実現します +- **[テキスト・画像・音声](docs/examples/scenario_7_multimodal.md)**：要約テキスト化して保存し、混在コンテンツを検索 -### 🎨 マルチモーダルサポート -- 🖼️ **[テキスト、画像、音声メモリ](docs/examples/scenario_7_multimodal.md)**：画像と音声を自動的にテキスト記述に変換して保存し、マルチモーダル混合コンテンツ（テキスト+画像+音声）の検索をサポートし、AI システムがより豊富なコンテキスト情報を理解できるようにします +### ストレージと検索 -### 💾 深く最適化されたデータストレージ -- 📦 **[サブストア（Sub Stores）サポート](docs/examples/scenario_6_sub_stores.md)**：サブストアによるデータのパーティション管理を実装し、自動ルーティングクエリをサポートし、超大规模データのクエリ性能とリソース利用率を大幅に向上させます -- 🔗 **[ハイブリッド検索](docs/examples/scenario_2_intelligent_memory.md)**：ベクトル検索、全文検索、グラフ検索のマルチチャネルリコール機能を融合し、LLM を通じてナレッジグラフを構築し、複雑なメモリ関係を正確に検索するためのマルチホップグラフトラバーサルをサポートします +- **[サブストア](docs/examples/scenario_6_sub_stores.md)**：パーティショニングと自動ルーティング（大規模向け） +- **[ハイブリッド検索](docs/examples/scenario_2_intelligent_memory.md)**：ベクトル + 全文 + グラフ（マルチホップ）、LLM 補助のグラフ構築 -## 🚀 クイックスタート +## クイックスタート -### 📥 インストール +流れ：**インストール** → **Python SDK** → **CLI** → **HTTP API と Dashboard** → **MCP**。設定は [.env.example](.env.example) と [設定ガイド](docs/guides/0003-configuration.md)。 + +### インストール ```bash pip install powermem ``` -### 💡 基本的な使用方法（SDK） - -**✨ 最も簡単な方法**：`.env` ファイルから自動的にメモリを作成！[設定ファイル参照](.env.example) +### 基本的な使い方（SDK） ```python from powermem import Memory, auto_config -# .env から自動的に読み込む config = auto_config() memory = Memory(config=config) -# メモリを追加 memory.add("ユーザーはコーヒーが好き", user_id="user123") -# メモリを検索 results = memory.search("ユーザー設定", user_id="user123") for result in results.get('results', []): print(f"- {result.get('memory')}") ``` -より詳細な例と使用パターンについては、[はじめにガイド](docs/guides/0001-getting_started.md) を参照してください。 +詳細：[はじめに](docs/guides/0001-getting_started.md)。 -### ⌨️ PowerMem CLI（1.0.0+） +### PowerMem CLI（1.0.0+） -PowerMem はコマンドラインインターフェース（`pmem`）を提供し、Python コードを書かずにメモリ操作、設定、バックアップ/復元、対話シェルを利用できます。 +`pmem` でメモリ操作、設定、バックアップ/復元、対話シェル。 ```bash -# メモリの追加と検索 pmem memory add "ユーザーはダークモードを好む" --user-id user123 pmem memory search "設定" --user-id user123 -# 設定と統計 pmem config show -pmem config init # 対話式 .env ウィザード +pmem config init pmem stats --json -# 対話シェル pmem shell ``` -完全な CLI リファレンスと例は [CLI 使用ガイド](docs/guides/0012-cli_usage.md) を参照してください。 - -### 🌐 HTTP API Server と Dashboard - -PowerMem は、すべてのコアメモリ管理機能を RESTful API で公開する本番環境対応の HTTP API サーバーを提供します。同時に **Dashboard**（パス `/dashboard/`）の Web 管理画面を提供します。 +参照：[CLI 使用ガイド](docs/guides/0012-cli_usage.md)。 -**SDK との関係**：API サーバーは内部で同じ PowerMem SDK を使用し、同じ設定（`.env` ファイル）を共有します。Python SDK と同じメモリ管理機能への HTTP インターフェースを提供し、PowerMem を非 Python アプリケーションでも利用可能にします。 +### HTTP API Server と Dashboard -**API サーバーの起動（Dashboard 含む）**： +SDK と **同じ** `.env` と PowerMem コア。REST、`/dashboard/`、`/docs`（OpenAPI）を提供。 ```bash -# 方法 1：CLI コマンドを使用（pip インストール後） powermem-server --host 0.0.0.0 --port 8000 +``` + +Docker / Compose： -# 方法 2：Docker を使用（API サーバー + Dashboard 同一コンテナ） +```bash docker run -d \ --name powermem-server \ -p 8000:8000 \ @@ -149,61 +140,27 @@ docker run -d \ --env-file .env \ oceanbase/powermem-server:latest -# または Docker Compose を使用（推奨） docker-compose -f docker/docker-compose.yml up -d ``` -起動後、同一サーバーで以下を提供します： -- すべてのメモリ操作の RESTful API エンドポイント -- **Dashboard**：`http://localhost:8000/dashboard/` でアクセス -- インタラクティブな API ドキュメント、`http://localhost:8000/docs` でアクセス可能 -- API Key 認証とレート制限サポート -- SDK と同じ設定（`.env` ファイル経由） - -完全な API ドキュメントと使用例については、[API サーバードキュメント](docs/api/0005-api_server.md) を参照してください。 - -### 🔌 MCP Server +詳細：[API Server](docs/api/0005-api_server.md)。 -PowerMem は、Claude Desktop などの MCP 互換クライアントとの統合を可能にするモデルコンテキストプロトコル（MCP）サーバーも提供します。MCP サーバーは、MCP プロトコルを通じて PowerMem のメモリ管理機能を公開し、AI アシスタントがシームレスにメモリにアクセスして管理できるようにします。 +### MCP Server -**SDK との関係**：MCP サーバーは、同じ PowerMem SDK を使用し、同じ設定（`.env` ファイル）を共有します。Python SDK で利用可能な同じメモリ管理機能への MCP インターフェースを提供し、PowerMem を MCP 互換の AI アシスタントでも利用可能にします。 - -**インストール**： +同じ SDK / `.env`。Claude Desktop 等の MCP クライアント向け。 ```bash -# PowerMem をインストール（必須） pip install powermem +# uv / uvx: https://docs.astral.sh/uv/getting-started/ -# uvx をインストール（まだインストールされていない場合） -# macOS/Linux の場合： -curl -LsSf https://astral.sh/uv/install.sh | sh - -# Windows の場合： -powershell -c "irm https://astral.sh/uv/install.ps1 | iex" -``` - -**MCP サーバーの起動**： - -```bash -# SSE モード（推奨、デフォルトポート 8000） uvx powermem-mcp sse - -# SSE モード、カスタムポート uvx powermem-mcp sse 8001 - -# Stdio モード uvx powermem-mcp stdio - -# Streamable HTTP モード（デフォルトポート 8000） uvx powermem-mcp streamable-http - -# Streamable HTTP モード、カスタムポート uvx powermem-mcp streamable-http 8001 ``` -**Claude Desktop との統合**： - -Claude Desktop 設定ファイルに次の設定を追加します： +Claude Desktop（SSE）設定例： ```json { @@ -215,46 +172,48 @@ Claude Desktop 設定ファイルに次の設定を追加します： } ``` -MCP サーバーは、メモリの追加、検索、更新、削除を含むメモリ管理ツールを提供します。完全な MCP ドキュメントと使用例については、[MCP サーバードキュメント](docs/api/0004-mcp.md) を参照してください。 +詳細：[MCP Server](docs/api/0004-mcp.md)。 -## 🔗 統合とデモ -- 🔗 **openclaw メモリプラグイン**: [openclaw](https://github.com/openclaw/openclaw) で HTTP API により PowerMem を長期メモリとして利用。インテリジェント抽出、エビングハウス忘却曲線、マルチエージェント分離に対応。[プラグインを参照](https://github.com/ob-labs/memory-powermem) -- 🔗 **LangChain 統合**: LangChain + PowerMem + OceanBase を使用して医療サポートロボットを構築、[例を参照](examples/langchain/README.md) -- 🔗 **LangGraph 統合**: LangGraph + PowerMem + OceanBase を使用してカスタマーサービスロボットを構築、[例を参照](examples/langgraph/README.md) +## エコシステムと統合 -## 📚 ドキュメント +### サンプル -- 📖 **[はじめに](docs/guides/0001-getting_started.md)**：インストールとクイックスタートガイド -- ⌨️ **[CLI 使用ガイド](docs/guides/0012-cli_usage.md)**：PowerMem CLI（pmem）リファレンス（1.0.0+） -- ⚙️ **[設定ガイド](docs/guides/0003-configuration.md)**：完全な設定オプション -- 🤖 **[マルチエージェントガイド](docs/guides/0005-multi_agent.md)**：マルチエージェントのシナリオと例 -- 🔌 **[統合ガイド](docs/guides/0009-integrations.md)**：統合ガイド -- 📦 **[サブストアガイド](docs/guides/0006-sub_stores.md)**：サブストアの使用方法と例 -- 📋 **[API ドキュメント](docs/api/overview.md)**：完全な API リファレンス -- 🏗️ **[アーキテクチャガイド](docs/architecture/overview.md)**：システムアーキテクチャと設計 -- 📓 **[例](docs/examples/overview.md)**：インタラクティブな Jupyter ノートブックとユースケース -- 👨‍💻 **[開発者ドキュメント](docs/development/overview.md)**：開発者ドキュメント +- **LangChain**：[医療サポート例](examples/langchain/README.md) +- **LangGraph**：[カスタマーサービス例](examples/langgraph/README.md) -## ⭐ ハイライト リリースノート +## ドキュメント -| Version | Release Date | Function | -|---------|-------|---------| -| 1.0.0 | 2026.03.16 |
  • PowerMem CLI (pmem)：メモリ操作、設定管理、バックアップ/リストア/マイグレーション、対話型シェル、シェル補完
  • Web Dashboard：メモリ管理と可視化
| -| 0.5.0 | 2026.02.06 |
  • SDK/API Server の設定ガバナンスを統一（pydantic-settings ベース）
  • OceanBase の native hybrid search を追加
  • Memory のクエリ処理を強化し、メモリ一覧のソートに対応
  • ユーザープロフィールでカスタムのネイティブ言語出力をサポート
| -| 0.4.0 | 2026.01.20 |
  • スパースベクトルサポート、高密度ベクトル、全文検索、スパースベクトルの3つの検索方式を融合したハイブリッド検索機能の強化
  • ユーザーメモリクエリ書き換え機能、ユーザープロフィールに基づいてクエリを自動的に書き換え、検索の再現率を向上
  • 既存テーブルのスキーマアップグレードとデータ移行ツール
| -| 0.3.0 | 2026.01.09 |
  • 本番環境対応の HTTP API サーバー、すべてのメモリ操作の RESTful エンドポイントを提供
  • Docker サポート、簡単なデプロイとコンテナ化を実現
| -| 0.2.0 | 2025.12.16 |
  • 高度なユーザープロフィール管理、AI アプリケーションの「千人千面」をサポート
  • テキスト、画像、音声メモリを含む拡張マルチモーダルサポート
| -| 0.1.0 | 2025.11.14 |
  • コアメモリ管理機能、メモリの永続ストレージをサポート
  • ベクトル、全文、グラフ検索をサポートするハイブリッド検索
  • LLM ベースの事実抽出によるインテリジェントメモリ抽出
  • エビングハウス忘却曲線に基づく全ライフサイクルメモリ管理をサポート
  • Multi-Agent メモリ管理をサポート
  • 複数のストレージバックエンドサポート（OceanBase、PostgreSQL、SQLite）
  • マルチホップグラフ検索による知識グラフの検索処理をサポート
| +| トピック | リンク | +|---------|--------| +| はじめに | [Guide](docs/guides/0001-getting_started.md) | +| CLI | [CLI](docs/guides/0012-cli_usage.md) | +| 設定 | [Configuration](docs/guides/0003-configuration.md) | +| マルチエージェント | [Multi-Agent](docs/guides/0005-multi_agent.md) | +| 統合 | [Integrations](docs/guides/0009-integrations.md) | +| サブストア | [Sub stores](docs/guides/0006-sub_stores.md) | +| API | [API overview](docs/api/overview.md) | +| アーキテクチャ | [Architecture](docs/architecture/overview.md) | +| 例 | [Examples](docs/examples/overview.md) | +| 開発 | [Development](docs/development/overview.md) | +## リリースハイライト -## 💬 サポート +| バージョン | 日付 | 内容 | +|------------|------|------| +| 1.0.0 | 2026-03-16 | CLI（`pmem`）：メモリ操作、設定、バックアップ/復元/マイグレーション、対話シェル、補完；Web Dashboard | +| 0.5.0 | 2026-02-06 | SDK/API 設定の統一（pydantic-settings）；OceanBase native hybrid search；Memory クエリと一覧ソート；プロフィールの言語カスタマイズ | +| 0.4.0 | 2026-01-20 | スパースベクトル混合検索；プロフィール起点のクエリ書き換え；スキーマ更新と移行ツール | +| 0.3.0 | 2026-01-09 | 本番向け HTTP API Server；Docker | +| 0.2.0 | 2025-12-16 | プロフィール強化；マルチモーダル（テキスト/画像/音声） | +| 0.1.0 | 2025-11-14 | コアメモリとハイブリッド検索；LLM 抽出；忘却曲線；マルチエージェント；OceanBase/PostgreSQL/SQLite；グラフ検索 | -- 🐛 **問題フィードバック**：[GitHub Issues](https://github.com/oceanbase/powermem/issues) -- 💭 **ディスカッション交流**：[GitHub Discussions](https://github.com/oceanbase/powermem/discussions) +## サポート ---- +- **Issues**：[GitHub Issues](https://github.com/oceanbase/powermem/issues) +- **ディスカッション**：[GitHub Discussions](https://github.com/oceanbase/powermem/discussions) -## 📄 ライセンス +--- -このプロジェクトは Apache License 2.0 の下でライセンスされています - 詳細については [LICENSE](LICENSE) ファイルを参照してください。 +## ライセンス +Apache License 2.0 — 詳細は [LICENSE](LICENSE)。 From 835159fa14db8b1592cd8d509971f9aec6173c75 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Wed, 25 Mar 2026 18:17:38 +0800 Subject: [PATCH 2/6] chore: make it clear Signed-off-by: Chojan Shang --- README.md | 146 +++++++++++-------------------------------------- README_CN.md | 146 +++++++++++-------------------------------------- README_JP.md | 151 +++++++++++++-------------------------------------- 3 files changed, 101 insertions(+), 342 deletions(-) diff --git a/README.md b/README.md index 7eb09c4..1302cfa 100644 --- a/README.md +++ b/README.md @@ -32,11 +32,13 @@ # PowerMem — Intelligent Memory for AI Applications -**PowerMem** is long-term memory infrastructure for AI apps: **hybrid vector + full-text + graph** retrieval, **Ebbinghaus-style forgetting**, and **LLM-driven memory extraction**, with **multi-agent isolation/sharing**, **user profiles**, and **multimodal** inputs (text, image, audio). The same feature set is available via **Python SDK**, **CLI (`pmem`)**, **HTTP API Server (with Dashboard)**, and **MCP Server**, all sharing **one `.env` configuration**. +PowerMem is a persistent memory layer for AI applications. It combines vector, full-text, and graph retrieval with LLM-driven memory extraction and time decay (Ebbinghaus-style forgetting), multi-agent isolation and collaboration, user profiles, and multimodal signals (text, image, audio). + +Python SDK, CLI (`pmem`), HTTP API Server (with Dashboard), and MCP Server share one `.env` configuration. See [.env.example](.env.example) and the [configuration guide](docs/guides/0003-configuration.md). > **News:** [OpenClaw](https://github.com/openclaw-ai/openclaw) can use PowerMem as long-term memory via [`memory-powermem`](https://github.com/ob-labs/memory-powermem) (`openclaw plugins install memory-powermem`). -## Why PowerMem +## Benchmark (LOCOMO)
@@ -44,51 +46,33 @@
-On the [LOCOMO](https://github.com/snap-research/locomo) benchmark vs. stuffing full conversation context: - -- **More accurate**: ~**48.77%** relative accuracy gain (78.70% vs. 52.9%) -- **Lower latency**: retrieval **p95** ~**1.44s** vs. **17.12s** (~**91.83%** faster) -- **Fewer tokens**: ~**0.9k** vs. **26k** (~**96.53%** reduction) without sacrificing the above - -## Core Features - -### Developer-friendly - -- **[Lightweight integration](docs/examples/scenario_1_basic_usage.md)**: Python SDK with `.env` auto-loading; also [CLI](docs/guides/0012-cli_usage.md) (`pmem`), [MCP Server](docs/api/0004-mcp.md), and [HTTP API Server](docs/api/0005-api_server.md) - -### Intelligent memory management +Compared to stuffing full conversation context on [LOCOMO](https://github.com/snap-research/locomo): -- **[Smart extraction](docs/examples/scenario_2_intelligent_memory.md)**: LLM-based fact extraction, deduplication, conflict resolution, and merging -- **[Ebbinghaus forgetting curve](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)**: time- and relevance-aware decay; prioritize recent, useful memories +| Dimension | Result | +|-----------|--------| +| Accuracy | 78.70% vs. 52.9% | +| Retrieval p95 latency | 1.44s vs. 17.12s | +| Tokens | ~0.9k vs. ~26k | -### User profiles +## Capabilities -- **[User profile](docs/examples/scenario_9_user_memory.md)**: profiles from history and behavior—personalization, companions, and similar use cases +**Interfaces and tooling** — [Python integration](docs/examples/scenario_1_basic_usage.md); [CLI](docs/guides/0012-cli_usage.md) (`pmem`); [HTTP API / Dashboard](docs/api/0005-api_server.md); [MCP](docs/api/0004-mcp.md). -### Multi-agent +**Memory pipeline and retrieval** — [Smart extraction and updates](docs/examples/scenario_2_intelligent_memory.md); [Ebbinghaus-style decay](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md); [Hybrid retrieval (vector / full-text / graph)](docs/examples/scenario_2_intelligent_memory.md); [Sub stores and routing](docs/examples/scenario_6_sub_stores.md). -- **[Shared / isolated memory](docs/examples/scenario_3_multi_agent.md)**: per-agent spaces, cross-agent collaboration, scope-based permissions +**Profiles and multi-agent** — [User profile](docs/examples/scenario_9_user_memory.md); [Shared / isolated memory and scopes](docs/examples/scenario_3_multi_agent.md). -### Multimodal +**Multimodal** — [Text, image, audio](docs/examples/scenario_7_multimodal.md). -- **[Text, image, audio](docs/examples/scenario_7_multimodal.md)**: media summarized to text for storage and mixed retrieval +## Quick start -### Storage & retrieval - -- **[Sub stores](docs/examples/scenario_6_sub_stores.md)**: partitioning and automatic routing for very large corpora -- **[Hybrid retrieval](docs/examples/scenario_2_intelligent_memory.md)**: vector + full-text + graph (multi-hop), with LLM-assisted graph construction - -## Quick Start - -Below: **Install** → **Python SDK** → **CLI (`pmem`)** → **HTTP API & Dashboard** → **MCP**. Options: [.env.example](.env.example) and the [configuration guide](docs/guides/0003-configuration.md). - -### Install +### 1. Install ```bash pip install powermem ``` -### Basic usage (SDK) +### 2. SDK example ```python from powermem import Memory, auto_config @@ -99,102 +83,36 @@ memory = Memory(config=config) memory.add("User likes coffee", user_id="user123") results = memory.search("user preferences", user_id="user123") -for result in results.get('results', []): +for result in results.get("results", []): print(f"- {result.get('memory')}") ``` More patterns: [Getting Started](docs/guides/0001-getting_started.md). -### PowerMem CLI (1.0.0+) - -`pmem` covers memory CRUD, config, backup/restore, and an interactive shell. - -```bash -pmem memory add "User prefers dark mode" --user-id user123 -pmem memory search "preferences" --user-id user123 - -pmem config show -pmem config init -pmem stats --json - -pmem shell -``` - -Full reference: [CLI usage](docs/guides/0012-cli_usage.md). - -### HTTP API Server & Dashboard - -Uses the **same** PowerMem SDK and `.env` as your code. Exposes REST, a **`/dashboard/`** UI, and **`/docs`** (OpenAPI). - -```bash -powermem-server --host 0.0.0.0 --port 8000 -``` - -Docker & Compose: - -```bash -docker run -d \ - --name powermem-server \ - -p 8000:8000 \ - -v $(pwd)/.env:/app/.env:ro \ - --env-file .env \ - oceanbase/powermem-server:latest - -docker-compose -f docker/docker-compose.yml up -d -``` - -Details: [API Server](docs/api/0005-api_server.md). +### 3. Other entry points -### MCP Server +| Mode | Typical commands | Docs | +|------|------------------|------| +| CLI | `pmem memory add` / `pmem memory search`; `pmem shell` | [CLI usage](docs/guides/0012-cli_usage.md) | +| HTTP + Dashboard | `powermem-server --host 0.0.0.0 --port 8000`; image `oceanbase/powermem-server:latest`; `docker-compose -f docker/docker-compose.yml` | [API Server](docs/api/0005-api_server.md) | +| MCP | `uvx powermem-mcp sse` (also stdio / streamable-http); requires `powermem` and `uv` | [MCP Server](docs/api/0004-mcp.md) | -Same SDK and `.env`; exposes memory tools to MCP clients (e.g. Claude Desktop). - -```bash -pip install powermem -# Install uv / uvx: https://docs.astral.sh/uv/getting-started/ - -uvx powermem-mcp sse -uvx powermem-mcp sse 8001 -uvx powermem-mcp stdio -uvx powermem-mcp streamable-http -uvx powermem-mcp streamable-http 8001 -``` +## Documentation and examples -Example Claude Desktop config (SSE): - -```json -{ - "mcpServers": { - "powermem": { - "url": "http://localhost:8000/mcp" - } - } -} -``` - -Details: [MCP Server](docs/api/0004-mcp.md). - -## Ecosystem & integrations - -### Examples - -- **LangChain**: [medical support chatbot](examples/langchain/README.md) -- **LangGraph**: [customer service bot](examples/langgraph/README.md) - -## Documentation - -| Topic | Link | -|------|------| +| Resource | Link | +|----------|------| | Getting started | [Guide](docs/guides/0001-getting_started.md) | -| CLI | [CLI usage](docs/guides/0012-cli_usage.md) | | Configuration | [Configuration](docs/guides/0003-configuration.md) | +| CLI | [CLI usage](docs/guides/0012-cli_usage.md) | | Multi-agent | [Multi-Agent](docs/guides/0005-multi_agent.md) | | Integrations | [Integrations](docs/guides/0009-integrations.md) | | Sub stores | [Sub stores](docs/guides/0006-sub_stores.md) | | API | [API overview](docs/api/overview.md) | | Architecture | [Architecture](docs/architecture/overview.md) | -| Examples | [Examples](docs/examples/overview.md) | +| Scenarios | [Examples](docs/examples/overview.md) | | Development | [Development](docs/development/overview.md) | +| Example: LangChain | [Medical support chatbot](examples/langchain/README.md) | +| Example: LangGraph | [Customer service bot](examples/langgraph/README.md) | ## Release highlights diff --git a/README_CN.md b/README_CN.md index c0fd124..622d4b6 100644 --- a/README_CN.md +++ b/README_CN.md @@ -33,11 +33,13 @@ # PowerMem — 智能 AI 记忆系统 -**PowerMem** 是面向 AI 应用的长期记忆基础设施：混合 **向量 / 全文 / 图** 检索，结合 **艾宾浩斯遗忘曲线** 与 **LLM 记忆抽取**，支持 **多智能体隔离与协作**、**用户画像** 与 **多模态**（文本、图像、音频）。同一套能力可通过 **Python SDK**、**CLI（`pmem`）**、**HTTP API Server（含 Dashboard）** 与 **MCP Server** 接入，配置统一（`.env`）。 +PowerMem 面向 AI 应用提供持久化记忆层：融合向量、全文与图检索，支持由 LLM 驱动的记忆抽取与时间衰减（艾宾浩斯曲线）、多智能体隔离与协作、用户画像以及文本/图像/音频等多模态线索。 + +使用 Python SDK、CLI（`pmem`）、HTTP API Server（含 Dashboard）或 MCP Server 时，共用同一套 `.env` 配置；完整选项见 [.env.example](.env.example) 与 [配置指南](docs/guides/0003-configuration.md)。 > **动态：** [OpenClaw](https://github.com/openclaw-ai/openclaw) 可通过插件 [memory-powermem](https://github.com/ob-labs/memory-powermem) 使用 PowerMem 作为长期记忆（`openclaw plugins install memory-powermem`）。 -## 为什么选择 PowerMem +## 基准表现（LOCOMO）
@@ -45,51 +47,33 @@
-在 [LOCOMO](https://github.com/snap-research/locomo) 基准上相对「全量上下文」方案： - -- **更准**：[准确率提升 48.77%]（78.70% VS 52.9%） -- **更快**：[检索 p95 延迟显著降低]（1.44s VS 17.12s，约 91.83%） -- **更省**：[Token 用量显著下降]（约 0.9k VS 26k，约 96.53%） - -## 核心特性 - -### 开发者友好 - -- **[轻量级接入](docs/examples/scenario_1_basic_usage.md)**：Python SDK 自动从 `.env` 加载配置；另支持 [CLI](docs/guides/0012-cli_usage.md)（`pmem`）、[MCP Server](docs/api/0004-mcp.md)、[HTTP API Server](docs/api/0005-api_server.md) - -### 智能记忆管理 +相对「全量上下文」基线（[LOCOMO](https://github.com/snap-research/locomo)）： -- **[智能记忆提取](docs/examples/scenario_2_intelligent_memory.md)**：基于 LLM 抽取事实、去重、消解冲突、合并相关记忆 -- **[艾宾浩斯遗忘曲线](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)**：按时间与相关性衰减，优先返回更近、更相关的记忆 - -### 用户画像 - -- **[用户画像](docs/examples/scenario_9_user_memory.md)**：从对话与行为构建/更新画像，服务个性化推荐、陪伴等场景 - -### 多智能体 +| 维度 | 结果 | +|------|------| +| 准确率 | 78.70% vs. 52.9% | +| 检索 p95 延迟 | 1.44s vs. 17.12s | +| Token 用量 | 约 0.9k vs. 26k | -- **[共享 / 隔离记忆](docs/examples/scenario_3_multi_agent.md)**：按智能体划分记忆空间，支持跨 Agent 协作与基于作用域的权限控制 +## 能力概览 -### 多模态 +**接入与工程化** — [Python 快速集成](docs/examples/scenario_1_basic_usage.md)；[CLI](docs/guides/0012-cli_usage.md)（`pmem`）；[HTTP API / Dashboard](docs/api/0005-api_server.md)；[MCP](docs/api/0004-mcp.md)。 -- **[文本 / 图像 / 语音](docs/examples/scenario_7_multimodal.md)**：媒体转述后入库，支持图文声混合检索 +**记忆管线与检索** — [智能抽取与更新](docs/examples/scenario_2_intelligent_memory.md)；[艾宾浩斯时间衰减](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)；[混合检索（向量 / 全文 / 图）](docs/examples/scenario_2_intelligent_memory.md)；[子存储与路由](docs/examples/scenario_6_sub_stores.md)。 -### 存储与检索 +**用户、画像与多智能体** — [用户画像](docs/examples/scenario_9_user_memory.md)；[共享 / 隔离记忆与作用域](docs/examples/scenario_3_multi_agent.md)。 -- **[子存储 Sub Stores](docs/examples/scenario_6_sub_stores.md)**：分区与自动路由，适合超大规模数据 -- **[混合检索](docs/examples/scenario_2_intelligent_memory.md)**：向量 + 全文 + 图（含多跳），并可由 LLM 辅助构图 +**多模态** — [文本 / 图像 / 语音](docs/examples/scenario_7_multimodal.md)。 ## 快速开始 -下面按顺序介绍：安装 → **Python SDK** → **CLI（`pmem`）** → **HTTP API 与 Dashboard** → **MCP**。配置见 [.env.example](.env.example) 与 [配置指南](docs/guides/0003-configuration.md)。 - -### 安装 +### 1. 安装 ```bash pip install powermem ``` -### 基本使用（SDK） +### 2. SDK 示例 ```python from powermem import Memory, auto_config @@ -100,102 +84,36 @@ memory = Memory(config=config) memory.add("用户喜欢咖啡", user_id="user123") results = memory.search("用户偏好", user_id="user123") -for result in results.get('results', []): +for result in results.get("results", []): print(f"- {result.get('memory')}") ``` -更多示例见 [入门指南](docs/guides/0001-getting_started.md)。 - -### PowerMem CLI（1.0.0+） - -`pmem` 支持记忆操作、配置、备份/恢复与交互式 shell。 - -```bash -pmem memory add "用户偏好深色模式" --user-id user123 -pmem memory search "偏好" --user-id user123 - -pmem config show -pmem config init -pmem stats --json - -pmem shell -``` - -详见 [CLI 使用指南](docs/guides/0012-cli_usage.md)。 - -### HTTP API Server 与 Dashboard - -与 SDK **共用**同一套 `.env` 配置；对外提供 REST、`/dashboard/` 管理界面与 `/docs` OpenAPI。 - -```bash -powermem-server --host 0.0.0.0 --port 8000 -``` - -Docker 与 Compose 示例： - -```bash -docker run -d \ - --name powermem-server \ - -p 8000:8000 \ - -v $(pwd)/.env:/app/.env:ro \ - --env-file .env \ - oceanbase/powermem-server:latest - -docker-compose -f docker/docker-compose.yml up -d -``` - -完整说明见 [API Server 文档](docs/api/0005-api_server.md)。 - -### MCP Server - -与 SDK **共用**配置；通过 MCP 把记忆能力接到 Claude Desktop 等客户端。 - -```bash -pip install powermem -# 安装 uv / uvx 见 https://docs.astral.sh/uv/getting-started/ - -uvx powermem-mcp sse # 推荐；默认 8000 -uvx powermem-mcp sse 8001 -uvx powermem-mcp stdio -uvx powermem-mcp streamable-http -uvx powermem-mcp streamable-http 8001 -``` - -Claude Desktop 配置示例（SSE）： - -```json -{ - "mcpServers": { - "powermem": { - "url": "http://localhost:8000/mcp" - } - } -} -``` +更多用法见 [入门指南](docs/guides/0001-getting_started.md)。 -详见 [MCP 文档](docs/api/0004-mcp.md)。 +### 3. 其他接入方式（命令入口） -## 生态与集成 - -### 示例项目 - -- **LangChain**：[医疗支持机器人示例](examples/langchain/README.md) -- **LangGraph**：[客服机器人示例](examples/langgraph/README.md) +| 方式 | 常用命令 | 文档 | +|------|----------|------| +| CLI | `pmem memory add` / `pmem memory search`；`pmem shell` | [CLI 使用指南](docs/guides/0012-cli_usage.md) | +| HTTP API + Dashboard | `powermem-server --host 0.0.0.0 --port 8000`；镜像 `oceanbase/powermem-server:latest`；`docker-compose -f docker/docker-compose.yml` | [API Server](docs/api/0005-api_server.md) | +| MCP | `uvx powermem-mcp sse`（及 stdio / streamable-http）；需已安装 `powermem` 与 `uv` | [MCP Server](docs/api/0004-mcp.md) | -## 文档索引 +## 文档与延伸 -| 主题 | 链接 | +| 类型 | 链接 | |------|------| | 入门 | [Getting Started](docs/guides/0001-getting_started.md) | -| CLI | [CLI 使用指南](docs/guides/0012-cli_usage.md) | | 配置 | [Configuration](docs/guides/0003-configuration.md) | +| CLI | [CLI 使用指南](docs/guides/0012-cli_usage.md) | | 多智能体 | [Multi-Agent](docs/guides/0005-multi_agent.md) | -| 集成 | [Integrations](docs/guides/0009-integrations.md) | +| 集成说明 | [Integrations](docs/guides/0009-integrations.md) | | 子存储 | [Sub Stores](docs/guides/0006-sub_stores.md) | | API | [API 总览](docs/api/overview.md) | | 架构 | [Architecture](docs/architecture/overview.md) | -| 示例 | [Examples](docs/examples/overview.md) | +| 场景示例 | [Examples](docs/examples/overview.md) | | 开发 | [Development](docs/development/overview.md) | +| 示例：LangChain | [医疗支持机器人](examples/langchain/README.md) | +| 示例：LangGraph | [客服机器人](examples/langgraph/README.md) | ## 版本要点 diff --git a/README_JP.md b/README_JP.md index daea405..916636c 100644 --- a/README_JP.md +++ b/README_JP.md @@ -32,11 +32,13 @@ # PowerMem — AI アプリ向けインテリジェントメモリ -**PowerMem** は AI アプリケーション向けの長期メモリ基盤です。**ベクトル・全文・グラフ**のハイブリッド検索、**エビングハウス型の忘却**、**LLM によるメモリ抽出**、**マルチエージェント分離/共有**、**ユーザープロフィール**、**マルチモーダル**（テキスト・画像・音声）をサポートします。同一機能を **Python SDK**、**CLI（`pmem`）**、**HTTP API Server（Dashboard 付き）**、**MCP Server** から利用でき、設定は **`.env` で統一**されます。 +PowerMem は AI アプリケーション向けの永続メモリ層です。ベクトル・全文・グラフ検索に加え、LLM によるメモリ抽出と時間減衰（エビングハウス型）、マルチエージェントの分離と協調、ユーザープロフィール、テキスト・画像・音声などのマルチモーダル手がかりを扱います。 + +Python SDK、CLI（`pmem`）、HTTP API Server（Dashboard 付き）、MCP Server は同一の `.env` を共有します。設定は [.env.example](.env.example) と [設定ガイド](docs/guides/0003-configuration.md) を参照してください。 > **ニュース:** [OpenClaw](https://github.com/openclaw-ai/openclaw) はプラグイン [memory-powermem](https://github.com/ob-labs/memory-powermem) により PowerMem を長期メモリとして利用できます（`openclaw plugins install memory-powermem`）。 -## PowerMem を選ぶ理由 +## ベンチマーク（LOCOMO）
@@ -44,51 +46,33 @@
-[LOCOMO](https://github.com/snap-research/locomo) ベンチマークにおいて、会話全文をコンテキストに載せる方式と比較： - -- **より正確**：精度の相対的な改善（78.70% vs. 52.9%、約 48.77%） -- **より高速**：検索 **p95** が約 **1.44s** vs. **17.12s**（約 91.83% 短縮） -- **トークン削減**：約 **0.9k** vs. **26k**（約 96.53% 削減）を性能を大きく損なわずに実現 - -## 主な機能 - -### 開発者体験 - -- **[軽量統合](docs/examples/scenario_1_basic_usage.md)**：`.env` を読み込む Python SDK に加え、[CLI](docs/guides/0012-cli_usage.md)（`pmem`）、[MCP Server](docs/api/0004-mcp.md)、[HTTP API Server](docs/api/0005-api_server.md) - -### メモリ管理 +会話全文をコンテキストに載せる方式との比較（[LOCOMO](https://github.com/snap-research/locomo)）： -- **[スマート抽出](docs/examples/scenario_2_intelligent_memory.md)**：LLM による事実抽出、重複排除、競合解消、マージ -- **[エビングハウス忘却曲線](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)**：時間・関連度に基づく減衰、最近・有用なメモリを優先 +| 観点 | 結果 | +|------|------| +| 精度 | 78.70% vs. 52.9% | +| 検索 p95 遅延 | 1.44s vs. 17.12s | +| トークン | 約 0.9k vs. 26k | -### ユーザープロフィール +## 機能概要 -- **[ユーザープロフィール](docs/examples/scenario_9_user_memory.md)**：履歴と行動からプロフィールを構築・更新（パーソナライズ、コンパニオン等） +**インターフェースとツール** — [Python 統合](docs/examples/scenario_1_basic_usage.md)；[CLI](docs/guides/0012-cli_usage.md)（`pmem`）；[HTTP API / Dashboard](docs/api/0005-api_server.md)；[MCP](docs/api/0004-mcp.md)。 -### マルチエージェント +**メモリパイプラインと検索** — [スマート抽出と更新](docs/examples/scenario_2_intelligent_memory.md)；[エビングハウス型減衰](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)；[ハイブリッド検索（ベクトル / 全文 / グラフ）](docs/examples/scenario_2_intelligent_memory.md)；[サブストアとルーティング](docs/examples/scenario_6_sub_stores.md)。 -- **[共有/分離メモリ](docs/examples/scenario_3_multi_agent.md)**：エージェント単位の空間、横断協業、スコープに基づく権限 +**プロフィールとマルチエージェント** — [ユーザープロフィール](docs/examples/scenario_9_user_memory.md)；[共有 / 分離メモリとスコープ](docs/examples/scenario_3_multi_agent.md)。 -### マルチモーダル - -- **[テキスト・画像・音声](docs/examples/scenario_7_multimodal.md)**：要約テキスト化して保存し、混在コンテンツを検索 - -### ストレージと検索 - -- **[サブストア](docs/examples/scenario_6_sub_stores.md)**：パーティショニングと自動ルーティング（大規模向け） -- **[ハイブリッド検索](docs/examples/scenario_2_intelligent_memory.md)**：ベクトル + 全文 + グラフ（マルチホップ）、LLM 補助のグラフ構築 +**マルチモーダル** — [テキスト・画像・音声](docs/examples/scenario_7_multimodal.md)。 ## クイックスタート -流れ：**インストール** → **Python SDK** → **CLI** → **HTTP API と Dashboard** → **MCP**。設定は [.env.example](.env.example) と [設定ガイド](docs/guides/0003-configuration.md)。 - -### インストール +### 1. インストール ```bash pip install powermem ``` -### 基本的な使い方（SDK） +### 2. SDK サンプル ```python from powermem import Memory, auto_config @@ -99,102 +83,36 @@ memory = Memory(config=config) memory.add("ユーザーはコーヒーが好き", user_id="user123") results = memory.search("ユーザー設定", user_id="user123") -for result in results.get('results', []): +for result in results.get("results", []): print(f"- {result.get('memory')}") ``` -詳細：[はじめに](docs/guides/0001-getting_started.md)。 - -### PowerMem CLI（1.0.0+） - -`pmem` でメモリ操作、設定、バックアップ/復元、対話シェル。 - -```bash -pmem memory add "ユーザーはダークモードを好む" --user-id user123 -pmem memory search "設定" --user-id user123 - -pmem config show -pmem config init -pmem stats --json - -pmem shell -``` - -参照：[CLI 使用ガイド](docs/guides/0012-cli_usage.md)。 +詳細は [はじめに](docs/guides/0001-getting_started.md) を参照してください。 -### HTTP API Server と Dashboard +### 3. その他の利用形態 -SDK と **同じ** `.env` と PowerMem コア。REST、`/dashboard/`、`/docs`（OpenAPI）を提供。 +| 形態 | 代表的なコマンド | ドキュメント | +|------|------------------|--------------| +| CLI | `pmem memory add` / `pmem memory search`；`pmem shell` | [CLI 使用ガイド](docs/guides/0012-cli_usage.md) | +| HTTP + Dashboard | `powermem-server --host 0.0.0.0 --port 8000`；イメージ `oceanbase/powermem-server:latest`；`docker-compose -f docker/docker-compose.yml` | [API Server](docs/api/0005-api_server.md) | +| MCP | `uvx powermem-mcp sse`（stdio / streamable-http も可）；`powermem` と `uv` が必要 | [MCP Server](docs/api/0004-mcp.md) | -```bash -powermem-server --host 0.0.0.0 --port 8000 -``` +## ドキュメントとサンプル -Docker / Compose： - -```bash -docker run -d \ - --name powermem-server \ - -p 8000:8000 \ - -v $(pwd)/.env:/app/.env:ro \ - --env-file .env \ - oceanbase/powermem-server:latest - -docker-compose -f docker/docker-compose.yml up -d -``` - -詳細：[API Server](docs/api/0005-api_server.md)。 - -### MCP Server - -同じ SDK / `.env`。Claude Desktop 等の MCP クライアント向け。 - -```bash -pip install powermem -# uv / uvx: https://docs.astral.sh/uv/getting-started/ - -uvx powermem-mcp sse -uvx powermem-mcp sse 8001 -uvx powermem-mcp stdio -uvx powermem-mcp streamable-http -uvx powermem-mcp streamable-http 8001 -``` - -Claude Desktop（SSE）設定例： - -```json -{ - "mcpServers": { - "powermem": { - "url": "http://localhost:8000/mcp" - } - } -} -``` - -詳細：[MCP Server](docs/api/0004-mcp.md)。 - -## エコシステムと統合 - -### サンプル - -- **LangChain**：[医療サポート例](examples/langchain/README.md) -- **LangGraph**：[カスタマーサービス例](examples/langgraph/README.md) - -## ドキュメント - -| トピック | リンク | -|---------|--------| +| 種類 | リンク | +|------|--------| | はじめに | [Guide](docs/guides/0001-getting_started.md) | -| CLI | [CLI](docs/guides/0012-cli_usage.md) | | 設定 | [Configuration](docs/guides/0003-configuration.md) | +| CLI | [CLI](docs/guides/0012-cli_usage.md) | | マルチエージェント | [Multi-Agent](docs/guides/0005-multi_agent.md) | | 統合 | [Integrations](docs/guides/0009-integrations.md) | | サブストア | [Sub stores](docs/guides/0006-sub_stores.md) | | API | [API overview](docs/api/overview.md) | | アーキテクチャ | [Architecture](docs/architecture/overview.md) | -| 例 | [Examples](docs/examples/overview.md) | +| シナリオ例 | [Examples](docs/examples/overview.md) | | 開発 | [Development](docs/development/overview.md) | +| サンプル：LangChain | [医療サポート](examples/langchain/README.md) | +| サンプル：LangGraph | [カスタマーサービス](examples/langgraph/README.md) | ## リリースハイライト @@ -217,3 +135,8 @@ Claude Desktop（SSE）設定例： ## ライセンス Apache License 2.0 — 詳細は [LICENSE](LICENSE)。 + +修正日文 README 中的错误链接 `0012-web_usage` → `0012-cli_usage`。 + +<｜tool▁calls▁begin｜><｜tool▁call▁begin｜> +StrReplace \ No newline at end of file From c039b65141be70be3fab48d020d48dcbbddea070 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 26 Mar 2026 10:47:26 +0800 Subject: [PATCH 3/6] docs: refine Signed-off-by: Chojan Shang --- README.md | 106 +++++++++++++++++++----------------------------- README_CN.md | 107 +++++++++++++++++++------------------------------ README_JP.md | 111 +++++++++++++++++++-------------------------------- 3 files changed, 123 insertions(+), 201 deletions(-) diff --git a/README.md b/README.md index 1302cfa..7c1e60e 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,30 @@ -

- - OceanBase Logo - -

- -

- - PowerMem PyPI - Downloads - - - GitHub commit activity - - - Package version - - - license - - - pyversions - - - Ask DeepWiki - - - Join Discord - -

- -[English](README.md) | [中文](README_CN.md) | [日本語](README_JP.md) - # PowerMem — Intelligent Memory for AI Applications -PowerMem is a persistent memory layer for AI applications. It combines vector, full-text, and graph retrieval with LLM-driven memory extraction and time decay (Ebbinghaus-style forgetting), multi-agent isolation and collaboration, user profiles, and multimodal signals (text, image, audio). - -Python SDK, CLI (`pmem`), HTTP API Server (with Dashboard), and MCP Server share one `.env` configuration. See [.env.example](.env.example) and the [configuration guide](docs/guides/0003-configuration.md). - -> **News:** [OpenClaw](https://github.com/openclaw-ai/openclaw) can use PowerMem as long-term memory via [`memory-powermem`](https://github.com/ob-labs/memory-powermem) (`openclaw plugins install memory-powermem`). +**Persistent memory for AI agents and applications.** -## Benchmark (LOCOMO) - -
+[![PyPI version](https://img.shields.io/pypi/v/powermem)](https://pypi.org/project/powermem/) +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/powermem/) +[![License Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) +[![GitHub](https://img.shields.io/badge/GitHub-oceanbase%2Fpowermem-181717?logo=github)](https://github.com/oceanbase/powermem) +[![Discord](https://img.shields.io/badge/Discord-community-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/74cF8vbNEs) -PowerMem LOCOMO Benchmark Metrics +*English · [中文](README_CN.md) · [日本語](README_JP.md)* -
+PowerMem combines vector, full-text, and graph retrieval with LLM-driven memory extraction and Ebbinghaus-style time decay. It supports multi-agent isolation, user profiles, and multimodal signals (text, image, audio). -Compared to stuffing full conversation context on [LOCOMO](https://github.com/snap-research/locomo): +Use the Python SDK, CLI (`pmem`), HTTP API Server (with Dashboard), or MCP Server — all share one `.env`. See [.env.example](.env.example) and the [configuration guide](docs/guides/0003-configuration.md). -| Dimension | Result | -|-----------|--------| -| Accuracy | 78.70% vs. 52.9% | -| Retrieval p95 latency | 1.44s vs. 17.12s | -| Tokens | ~0.9k vs. ~26k | - -## Capabilities - -**Interfaces and tooling** — [Python integration](docs/examples/scenario_1_basic_usage.md); [CLI](docs/guides/0012-cli_usage.md) (`pmem`); [HTTP API / Dashboard](docs/api/0005-api_server.md); [MCP](docs/api/0004-mcp.md). - -**Memory pipeline and retrieval** — [Smart extraction and updates](docs/examples/scenario_2_intelligent_memory.md); [Ebbinghaus-style decay](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md); [Hybrid retrieval (vector / full-text / graph)](docs/examples/scenario_2_intelligent_memory.md); [Sub stores and routing](docs/examples/scenario_6_sub_stores.md). - -**Profiles and multi-agent** — [User profile](docs/examples/scenario_9_user_memory.md); [Shared / isolated memory and scopes](docs/examples/scenario_3_multi_agent.md). - -**Multimodal** — [Text, image, audio](docs/examples/scenario_7_multimodal.md). +> **News:** [OpenClaw](https://github.com/openclaw-ai/openclaw) can use PowerMem as long-term memory via [`memory-powermem`](https://github.com/ob-labs/memory-powermem) (`openclaw plugins install memory-powermem`). ## Quick start -### 1. Install +### Install ```bash pip install powermem ``` -### 2. SDK example +### SDK example ```python from powermem import Memory, auto_config @@ -89,7 +41,7 @@ for result in results.get("results", []): More patterns: [Getting Started](docs/guides/0001-getting_started.md). -### 3. Other entry points +### Other entry points | Mode | Typical commands | Docs | |------|------------------|------| @@ -97,6 +49,32 @@ More patterns: [Getting Started](docs/guides/0001-getting_started.md). | HTTP + Dashboard | `powermem-server --host 0.0.0.0 --port 8000`; image `oceanbase/powermem-server:latest`; `docker-compose -f docker/docker-compose.yml` | [API Server](docs/api/0005-api_server.md) | | MCP | `uvx powermem-mcp sse` (also stdio / streamable-http); requires `powermem` and `uv` | [MCP Server](docs/api/0004-mcp.md) | +## Benchmark (LOCOMO) + +
+ +PowerMem LOCOMO Benchmark Metrics + +
+ +Compared to stuffing full conversation context on [LOCOMO](https://github.com/snap-research/locomo): + +| Dimension | Result | +|-----------|--------| +| Accuracy | 78.70% vs. 52.9% | +| Retrieval p95 latency | 1.44s vs. 17.12s | +| Tokens | ~0.9k vs. ~26k | + +## Capabilities + +**Interfaces and tooling** — [Python integration](docs/examples/scenario_1_basic_usage.md); [CLI](docs/guides/0012-cli_usage.md) (`pmem`); [HTTP API / Dashboard](docs/api/0005-api_server.md); [MCP](docs/api/0004-mcp.md). + +**Memory pipeline and retrieval** — [Smart extraction and updates](docs/examples/scenario_2_intelligent_memory.md); [Ebbinghaus-style decay](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md); [Hybrid retrieval (vector / full-text / graph)](docs/examples/scenario_2_intelligent_memory.md); [Sub stores and routing](docs/examples/scenario_6_sub_stores.md). + +**Profiles and multi-agent** — [User profile](docs/examples/scenario_9_user_memory.md); [Shared / isolated memory and scopes](docs/examples/scenario_3_multi_agent.md). + +**Multimodal** — [Text, image, audio](docs/examples/scenario_7_multimodal.md). + ## Documentation and examples | Resource | Link | @@ -127,10 +105,8 @@ More patterns: [Getting Started](docs/guides/0001-getting_started.md). ## Support -- **Issues**: [GitHub Issues](https://github.com/oceanbase/powermem/issues) -- **Discussions**: [GitHub Discussions](https://github.com/oceanbase/powermem/discussions) - ---- +- [GitHub Issues](https://github.com/oceanbase/powermem/issues) +- [GitHub Discussions](https://github.com/oceanbase/powermem/discussions) ## License diff --git a/README_CN.md b/README_CN.md index 622d4b6..9e61ee4 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,79 +1,30 @@ -

- - OceanBase Logo - -

- -

- - PowerMem PyPI - Downloads - - - GitHub commit activity - - - Package version - - - license - - - pyversions - - - Ask DeepWiki - - zread - - Join Discord - -

- -[English](README.md) | [中文](README_CN.md) | [日本語](README_JP.md) - # PowerMem — 智能 AI 记忆系统 -PowerMem 面向 AI 应用提供持久化记忆层：融合向量、全文与图检索，支持由 LLM 驱动的记忆抽取与时间衰减（艾宾浩斯曲线）、多智能体隔离与协作、用户画像以及文本/图像/音频等多模态线索。 - -使用 Python SDK、CLI（`pmem`）、HTTP API Server（含 Dashboard）或 MCP Server 时，共用同一套 `.env` 配置；完整选项见 [.env.example](.env.example) 与 [配置指南](docs/guides/0003-configuration.md)。 - -> **动态：** [OpenClaw](https://github.com/openclaw-ai/openclaw) 可通过插件 [memory-powermem](https://github.com/ob-labs/memory-powermem) 使用 PowerMem 作为长期记忆（`openclaw plugins install memory-powermem`）。 +**面向 AI 应用与智能体的持久化记忆层。** -## 基准表现（LOCOMO） - -
+[![PyPI version](https://img.shields.io/pypi/v/powermem)](https://pypi.org/project/powermem/) +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/powermem/) +[![License Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) +[![GitHub](https://img.shields.io/badge/GitHub-oceanbase%2Fpowermem-181717?logo=github)](https://github.com/oceanbase/powermem) +[![Discord](https://img.shields.io/badge/Discord-社区-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/74cF8vbNEs) -PowerMem LOCOMO 压测指标 +*[English](README.md) · 中文 · [日本語](README_JP.md)* -
+PowerMem 融合向量、全文与图检索，支持由 LLM 驱动的记忆抽取与艾宾浩斯型时间衰减，以及多智能体隔离、用户画像和文本/图像/音频等多模态线索。 -相对「全量上下文」基线（[LOCOMO](https://github.com/snap-research/locomo)）： +通过 Python SDK、CLI（`pmem`）、HTTP API Server（含 Dashboard）或 MCP Server 接入时共用同一套 `.env`；完整选项见 [.env.example](.env.example) 与 [配置指南](docs/guides/0003-configuration.md)。 -| 维度 | 结果 | -|------|------| -| 准确率 | 78.70% vs. 52.9% | -| 检索 p95 延迟 | 1.44s vs. 17.12s | -| Token 用量 | 约 0.9k vs. 26k | - -## 能力概览 - -**接入与工程化** — [Python 快速集成](docs/examples/scenario_1_basic_usage.md)；[CLI](docs/guides/0012-cli_usage.md)（`pmem`）；[HTTP API / Dashboard](docs/api/0005-api_server.md)；[MCP](docs/api/0004-mcp.md)。 - -**记忆管线与检索** — [智能抽取与更新](docs/examples/scenario_2_intelligent_memory.md)；[艾宾浩斯时间衰减](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)；[混合检索（向量 / 全文 / 图）](docs/examples/scenario_2_intelligent_memory.md)；[子存储与路由](docs/examples/scenario_6_sub_stores.md)。 - -**用户、画像与多智能体** — [用户画像](docs/examples/scenario_9_user_memory.md)；[共享 / 隔离记忆与作用域](docs/examples/scenario_3_multi_agent.md)。 - -**多模态** — [文本 / 图像 / 语音](docs/examples/scenario_7_multimodal.md)。 +> **动态：** [OpenClaw](https://github.com/openclaw-ai/openclaw) 可通过插件 [memory-powermem](https://github.com/ob-labs/memory-powermem) 使用 PowerMem 作为长期记忆（`openclaw plugins install memory-powermem`）。 ## 快速开始 -### 1. 安装 +### 安装 ```bash pip install powermem ``` -### 2. SDK 示例 +### SDK 示例 ```python from powermem import Memory, auto_config @@ -90,7 +41,7 @@ for result in results.get("results", []): 更多用法见 [入门指南](docs/guides/0001-getting_started.md)。 -### 3. 其他接入方式（命令入口） +### 其他接入方式（命令入口） | 方式 | 常用命令 | 文档 | |------|----------|------| @@ -98,6 +49,32 @@ for result in results.get("results", []): | HTTP API + Dashboard | `powermem-server --host 0.0.0.0 --port 8000`；镜像 `oceanbase/powermem-server:latest`；`docker-compose -f docker/docker-compose.yml` | [API Server](docs/api/0005-api_server.md) | | MCP | `uvx powermem-mcp sse`（及 stdio / streamable-http）；需已安装 `powermem` 与 `uv` | [MCP Server](docs/api/0004-mcp.md) | +## 基准表现（LOCOMO） + +
+ +PowerMem LOCOMO 压测指标 + +
+ +相对「全量上下文」基线（[LOCOMO](https://github.com/snap-research/locomo)）： + +| 维度 | 结果 | +|------|------| +| 准确率 | 78.70% vs. 52.9% | +| 检索 p95 延迟 | 1.44s vs. 17.12s | +| Token 用量 | 约 0.9k vs. 26k | + +## 能力概览 + +**接入与工程化** — [Python 快速集成](docs/examples/scenario_1_basic_usage.md)；[CLI](docs/guides/0012-cli_usage.md)（`pmem`）；[HTTP API / Dashboard](docs/api/0005-api_server.md)；[MCP](docs/api/0004-mcp.md)。 + +**记忆管线与检索** — [智能抽取与更新](docs/examples/scenario_2_intelligent_memory.md)；[艾宾浩斯时间衰减](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)；[混合检索（向量 / 全文 / 图）](docs/examples/scenario_2_intelligent_memory.md)；[子存储与路由](docs/examples/scenario_6_sub_stores.md)。 + +**用户、画像与多智能体** — [用户画像](docs/examples/scenario_9_user_memory.md)；[共享 / 隔离记忆与作用域](docs/examples/scenario_3_multi_agent.md)。 + +**多模态** — [文本 / 图像 / 语音](docs/examples/scenario_7_multimodal.md)。 + ## 文档与延伸 | 类型 | 链接 | @@ -128,10 +105,8 @@ for result in results.get("results", []): ## 支持 -- **问题反馈**：[GitHub Issues](https://github.com/oceanbase/powermem/issues) -- **讨论**：[GitHub Discussions](https://github.com/oceanbase/powermem/discussions) - ---- +- [GitHub Issues](https://github.com/oceanbase/powermem/issues) +- [GitHub Discussions](https://github.com/oceanbase/powermem/discussions) ## 许可证 diff --git a/README_JP.md b/README_JP.md index 916636c..b033d05 100644 --- a/README_JP.md +++ b/README_JP.md @@ -1,78 +1,30 @@ -

- - OceanBase Logo - -

- -

- - PowerMem PyPI - Downloads - - - GitHub commit activity - - - Package version - - - license - - - pyversions - - - Ask DeepWiki - - - Join Discord - -

- -[English](README.md) | [中文](README_CN.md) | [日本語](README_JP.md) - # PowerMem — AI アプリ向けインテリジェントメモリ -PowerMem は AI アプリケーション向けの永続メモリ層です。ベクトル・全文・グラフ検索に加え、LLM によるメモリ抽出と時間減衰（エビングハウス型）、マルチエージェントの分離と協調、ユーザープロフィール、テキスト・画像・音声などのマルチモーダル手がかりを扱います。 - -Python SDK、CLI（`pmem`）、HTTP API Server（Dashboard 付き）、MCP Server は同一の `.env` を共有します。設定は [.env.example](.env.example) と [設定ガイド](docs/guides/0003-configuration.md) を参照してください。 - -> **ニュース:** [OpenClaw](https://github.com/openclaw-ai/openclaw) はプラグイン [memory-powermem](https://github.com/ob-labs/memory-powermem) により PowerMem を長期メモリとして利用できます（`openclaw plugins install memory-powermem`）。 +**AI アプリケーションとエージェント向けの永続メモリ層。** -## ベンチマーク（LOCOMO） - -
+[![PyPI version](https://img.shields.io/pypi/v/powermem)](https://pypi.org/project/powermem/) +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/powermem/) +[![License Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE) +[![GitHub](https://img.shields.io/badge/GitHub-oceanbase%2Fpowermem-181717?logo=github)](https://github.com/oceanbase/powermem) +[![Discord](https://img.shields.io/badge/Discord-community-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/74cF8vbNEs) -PowerMem LOCOMO ベンチマーク指標 +*[English](README.md) · [中文](README_CN.md) · 日本語* -
+PowerMem はベクトル・全文・グラフ検索に加え、LLM によるメモリ抽出とエビングハウス型の時間減衰、マルチエージェント分離、ユーザープロフィール、テキスト・画像・音声などのマルチモーダル手がかりを扱います。 -会話全文をコンテキストに載せる方式との比較（[LOCOMO](https://github.com/snap-research/locomo)）： +Python SDK、CLI（`pmem`）、HTTP API Server（Dashboard 付き）、MCP Server は同一の `.env` を共有します。[.env.example](.env.example) と [設定ガイド](docs/guides/0003-configuration.md) を参照してください。 -| 観点 | 結果 | -|------|------| -| 精度 | 78.70% vs. 52.9% | -| 検索 p95 遅延 | 1.44s vs. 17.12s | -| トークン | 約 0.9k vs. 26k | - -## 機能概要 - -**インターフェースとツール** — [Python 統合](docs/examples/scenario_1_basic_usage.md)；[CLI](docs/guides/0012-cli_usage.md)（`pmem`）；[HTTP API / Dashboard](docs/api/0005-api_server.md)；[MCP](docs/api/0004-mcp.md)。 - -**メモリパイプラインと検索** — [スマート抽出と更新](docs/examples/scenario_2_intelligent_memory.md)；[エビングハウス型減衰](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)；[ハイブリッド検索（ベクトル / 全文 / グラフ）](docs/examples/scenario_2_intelligent_memory.md)；[サブストアとルーティング](docs/examples/scenario_6_sub_stores.md)。 - -**プロフィールとマルチエージェント** — [ユーザープロフィール](docs/examples/scenario_9_user_memory.md)；[共有 / 分離メモリとスコープ](docs/examples/scenario_3_multi_agent.md)。 - -**マルチモーダル** — [テキスト・画像・音声](docs/examples/scenario_7_multimodal.md)。 +> **ニュース:** [OpenClaw](https://github.com/openclaw-ai/openclaw) はプラグイン [memory-powermem](https://github.com/ob-labs/memory-powermem) により PowerMem を長期メモリとして利用できます（`openclaw plugins install memory-powermem`）。 ## クイックスタート -### 1. インストール +### インストール ```bash pip install powermem ``` -### 2. SDK サンプル +### SDK サンプル ```python from powermem import Memory, auto_config @@ -89,7 +41,7 @@ for result in results.get("results", []): 詳細は [はじめに](docs/guides/0001-getting_started.md) を参照してください。 -### 3. その他の利用形態 +### その他の利用形態 | 形態 | 代表的なコマンド | ドキュメント | |------|------------------|--------------| @@ -97,6 +49,32 @@ for result in results.get("results", []): | HTTP + Dashboard | `powermem-server --host 0.0.0.0 --port 8000`；イメージ `oceanbase/powermem-server:latest`；`docker-compose -f docker/docker-compose.yml` | [API Server](docs/api/0005-api_server.md) | | MCP | `uvx powermem-mcp sse`（stdio / streamable-http も可）；`powermem` と `uv` が必要 | [MCP Server](docs/api/0004-mcp.md) | +## ベンチマーク（LOCOMO） + +
+ +PowerMem LOCOMO ベンチマーク指標 + +
+ +会話全文をコンテキストに載せる方式との比較（[LOCOMO](https://github.com/snap-research/locomo)）： + +| 観点 | 結果 | +|------|------| +| 精度 | 78.70% vs. 52.9% | +| 検索 p95 遅延 | 1.44s vs. 17.12s | +| トークン | 約 0.9k vs. 26k | + +## 機能概要 + +**インターフェースとツール** — [Python 統合](docs/examples/scenario_1_basic_usage.md)；[CLI](docs/guides/0012-cli_usage.md)（`pmem`）；[HTTP API / Dashboard](docs/api/0005-api_server.md)；[MCP](docs/api/0004-mcp.md)。 + +**メモリパイプラインと検索** — [スマート抽出と更新](docs/examples/scenario_2_intelligent_memory.md)；[エビングハウス型減衰](docs/examples/scenario_8_ebbinghaus_forgetting_curve.md)；[ハイブリッド検索（ベクトル / 全文 / グラフ）](docs/examples/scenario_2_intelligent_memory.md)；[サブストアとルーティング](docs/examples/scenario_6_sub_stores.md)。 + +**プロフィールとマルチエージェント** — [ユーザープロフィール](docs/examples/scenario_9_user_memory.md)；[共有 / 分離メモリとスコープ](docs/examples/scenario_3_multi_agent.md)。 + +**マルチモーダル** — [テキスト・画像・音声](docs/examples/scenario_7_multimodal.md)。 + ## ドキュメントとサンプル | 種類 | リンク | @@ -127,16 +105,9 @@ for result in results.get("results", []): ## サポート -- **Issues**：[GitHub Issues](https://github.com/oceanbase/powermem/issues) -- **ディスカッション**：[GitHub Discussions](https://github.com/oceanbase/powermem/discussions) - ---- +- [GitHub Issues](https://github.com/oceanbase/powermem/issues) +- [GitHub Discussions](https://github.com/oceanbase/powermem/discussions) ## ライセンス Apache License 2.0 — 詳細は [LICENSE](LICENSE)。 - -修正日文 README 中的错误链接 `0012-web_usage` → `0012-cli_usage`。 - -<｜tool▁calls▁begin｜><｜tool▁call▁begin｜> -StrReplace \ No newline at end of file From 8ff32e621afd7ee9d2e4032f61b173af96565a30 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 26 Mar 2026 10:54:34 +0800 Subject: [PATCH 4/6] chore: remove subtitle Signed-off-by: Chojan Shang --- README.md | 2 +- README_CN.md | 2 +- README_JP.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7c1e60e..c3d3b2d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# PowerMem — Intelligent Memory for AI Applications +# PowerMem **Persistent memory for AI agents and applications.** diff --git a/README_CN.md b/README_CN.md index 9e61ee4..63d86ab 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,4 +1,4 @@ -# PowerMem — 智能 AI 记忆系统 +# PowerMem **面向 AI 应用与智能体的持久化记忆层。** diff --git a/README_JP.md b/README_JP.md index b033d05..a446d13 100644 --- a/README_JP.md +++ b/README_JP.md @@ -1,4 +1,4 @@ -# PowerMem — AI アプリ向けインテリジェントメモリ +# PowerMem **AI アプリケーションとエージェント向けの永続メモリ層。** From c768cbd99c7625f16d95d213307bf8f698b59d5a Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 26 Mar 2026 10:59:43 +0800 Subject: [PATCH 5/6] docs: re-org docs and examples Signed-off-by: Chojan Shang --- README.md | 35 +++++++++++++++++++---------------- README_CN.md | 33 ++++++++++++++++++--------------- README_JP.md | 35 +++++++++++++++++++---------------- 3 files changed, 56 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index c3d3b2d..79d4e7d 100644 --- a/README.md +++ b/README.md @@ -75,22 +75,25 @@ Compared to stuffing full conversation context on [LOCOMO](https://github.com/sn **Multimodal** — [Text, image, audio](docs/examples/scenario_7_multimodal.md). -## Documentation and examples - -| Resource | Link | -|----------|------| -| Getting started | [Guide](docs/guides/0001-getting_started.md) | -| Configuration | [Configuration](docs/guides/0003-configuration.md) | -| CLI | [CLI usage](docs/guides/0012-cli_usage.md) | -| Multi-agent | [Multi-Agent](docs/guides/0005-multi_agent.md) | -| Integrations | [Integrations](docs/guides/0009-integrations.md) | -| Sub stores | [Sub stores](docs/guides/0006-sub_stores.md) | -| API | [API overview](docs/api/overview.md) | -| Architecture | [Architecture](docs/architecture/overview.md) | -| Scenarios | [Examples](docs/examples/overview.md) | -| Development | [Development](docs/development/overview.md) | -| Example: LangChain | [Medical support chatbot](examples/langchain/README.md) | -| Example: LangGraph | [Customer service bot](examples/langgraph/README.md) | +## Docs + +- [Getting started](docs/guides/0001-getting_started.md) — install, `.env`, and first `Memory` usage +- [Configuration](docs/guides/0003-configuration.md) — settings model, storage backends, environment variables +- [Architecture](docs/architecture/overview.md) — major components, storage layout, and retrieval flow +- [API & services](docs/api/overview.md) — REST, MCP, HTTP server, and Python-facing APIs +- [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 +- [Docker & deployment](docker/README.md) — images, Compose, and running the API server +- [Development](docs/development/overview.md) — local setup, tests, and contributing + +More topics: [Sub stores](docs/guides/0006-sub_stores.md), [guides index](docs/guides/overview.md). + +## Examples + +- [Scenarios & notebooks](docs/examples/overview.md) — walkthroughs by use case (basic usage, multimodal, forgetting curve, and more) +- [LangChain sample](examples/langchain/README.md) — medical support chatbot +- [LangGraph sample](examples/langgraph/README.md) — customer service bot ## Release highlights diff --git a/README_CN.md b/README_CN.md index 63d86ab..230edae 100644 --- a/README_CN.md +++ b/README_CN.md @@ -75,22 +75,25 @@ for result in results.get("results", []): **多模态** — [文本 / 图像 / 语音](docs/examples/scenario_7_multimodal.md)。 -## 文档与延伸 +## 文档 -| 类型 | 链接 | -|------|------| -| 入门 | [Getting Started](docs/guides/0001-getting_started.md) | -| 配置 | [Configuration](docs/guides/0003-configuration.md) | -| CLI | [CLI 使用指南](docs/guides/0012-cli_usage.md) | -| 多智能体 | [Multi-Agent](docs/guides/0005-multi_agent.md) | -| 集成说明 | [Integrations](docs/guides/0009-integrations.md) | -| 子存储 | [Sub Stores](docs/guides/0006-sub_stores.md) | -| API | [API 总览](docs/api/overview.md) | -| 架构 | [Architecture](docs/architecture/overview.md) | -| 场景示例 | [Examples](docs/examples/overview.md) | -| 开发 | [Development](docs/development/overview.md) | -| 示例：LangChain | [医疗支持机器人](examples/langchain/README.md) | -| 示例：LangGraph | [客服机器人](examples/langgraph/README.md) | +- [入门指南](docs/guides/0001-getting_started.md) — 安装、`.env`、首个 `Memory` 用法 +- [配置说明](docs/guides/0003-configuration.md) — 配置模型、存储后端、环境变量 +- [架构](docs/architecture/overview.md) — 主要组件、存储布局、检索主路径 +- [API 与服务](docs/api/overview.md) — REST、MCP、HTTP 服务与 Python 接口入口 +- [CLI](docs/guides/0012-cli_usage.md) — `pmem` 命令、交互 shell、备份与迁移 +- [多智能体](docs/guides/0005-multi_agent.md) — 作用域、隔离与跨 Agent 共享 +- [集成说明](docs/guides/0009-integrations.md) — LangChain 等与框架对接 +- [Docker 与部署](docker/README.md) — 镜像、Compose、运行 API 服务 +- [开发文档](docs/development/overview.md) — 本地环境、测试、参与贡献 + +更多：[子存储](docs/guides/0006-sub_stores.md)、[指南索引](docs/guides/overview.md)。 + +## 示例 + +- [场景与 Notebook](docs/examples/overview.md) — 按用例的说明与笔记本（基础、多模态、遗忘曲线等） +- [LangChain 示例](examples/langchain/README.md) — 医疗支持机器人 +- [LangGraph 示例](examples/langgraph/README.md) — 客服机器人 ## 版本要点 diff --git a/README_JP.md b/README_JP.md index a446d13..679611e 100644 --- a/README_JP.md +++ b/README_JP.md @@ -75,22 +75,25 @@ for result in results.get("results", []): **マルチモーダル** — [テキスト・画像・音声](docs/examples/scenario_7_multimodal.md)。 -## ドキュメントとサンプル - -| 種類 | リンク | -|------|--------| -| はじめに | [Guide](docs/guides/0001-getting_started.md) | -| 設定 | [Configuration](docs/guides/0003-configuration.md) | -| CLI | [CLI](docs/guides/0012-cli_usage.md) | -| マルチエージェント | [Multi-Agent](docs/guides/0005-multi_agent.md) | -| 統合 | [Integrations](docs/guides/0009-integrations.md) | -| サブストア | [Sub stores](docs/guides/0006-sub_stores.md) | -| API | [API overview](docs/api/overview.md) | -| アーキテクチャ | [Architecture](docs/architecture/overview.md) | -| シナリオ例 | [Examples](docs/examples/overview.md) | -| 開発 | [Development](docs/development/overview.md) | -| サンプル：LangChain | [医療サポート](examples/langchain/README.md) | -| サンプル：LangGraph | [カスタマーサービス](examples/langgraph/README.md) | +## ドキュメント + +- [はじめに](docs/guides/0001-getting_started.md) — インストール、`.env`、最初の `Memory` 利用 +- [設定](docs/guides/0003-configuration.md) — 設定モデル、ストレージバックエンド、環境変数 +- [アーキテクチャ](docs/architecture/overview.md) — 主要コンポーネント、ストレージ構成、検索の流れ +- [API とサービス](docs/api/overview.md) — REST、MCP、HTTP サーバー、Python 向け API +- [CLI](docs/guides/0012-cli_usage.md) — `pmem` コマンド、対話シェル、バックアップとマイグレーション +- [マルチエージェント](docs/guides/0005-multi_agent.md) — スコープ、分離、エージェント間共有 +- [統合](docs/guides/0009-integrations.md) — LangChain などフレームワーク連携 +- [Docker とデプロイ](docker/README.md) — イメージ、Compose、API サーバーの実行 +- [開発](docs/development/overview.md) — ローカル環境、テスト、コントリビューション + +その他：[サブストア](docs/guides/0006-sub_stores.md)、[ガイド一覧](docs/guides/overview.md)。 + +## サンプル + +- [シナリオと Notebook](docs/examples/overview.md) — ユースケース別の手順とノート（基本、マルチモーダル、忘却曲線など） +- [LangChain サンプル](examples/langchain/README.md) — 医療サポートチャットボット +- [LangGraph サンプル](examples/langgraph/README.md) — カスタマーサービスボット ## リリースハイライト From 8e6b3985237d754c8dd9d7507cc1cabf89d55c48 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 26 Mar 2026 11:07:03 +0800 Subject: [PATCH 6/6] docs: minor fix Signed-off-by: Chojan Shang --- README.md | 6 +++--- README_CN.md | 6 +++--- README_JP.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 79d4e7d..9e85774 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ PowerMem combines vector, full-text, and graph retrieval with LLM-driven memory Use the Python SDK, CLI (`pmem`), HTTP API Server (with Dashboard), or MCP Server — all share one `.env`. See [.env.example](.env.example) and the [configuration guide](docs/guides/0003-configuration.md). -> **News:** [OpenClaw](https://github.com/openclaw-ai/openclaw) can use PowerMem as long-term memory via [`memory-powermem`](https://github.com/ob-labs/memory-powermem) (`openclaw plugins install memory-powermem`). +> **News:** [OpenClaw](https://github.com/openclaw/openclaw) can use PowerMem as long-term memory via [`memory-powermem`](https://github.com/ob-labs/memory-powermem) (`openclaw plugins install memory-powermem`). ## Quick start @@ -92,8 +92,8 @@ More topics: [Sub stores](docs/guides/0006-sub_stores.md), [guides index](docs/g ## Examples - [Scenarios & notebooks](docs/examples/overview.md) — walkthroughs by use case (basic usage, multimodal, forgetting curve, and more) -- [LangChain sample](examples/langchain/README.md) — medical support chatbot -- [LangGraph sample](examples/langgraph/README.md) — customer service bot +- [LangChain sample](examples/langchain/README.md) — medical support chatbot (LangChain + PowerMem + OceanBase) +- [LangGraph sample](examples/langgraph/README.md) — customer service bot (LangGraph + PowerMem + OceanBase) ## Release highlights diff --git a/README_CN.md b/README_CN.md index 230edae..2d5e2ec 100644 --- a/README_CN.md +++ b/README_CN.md @@ -14,7 +14,7 @@ PowerMem 融合向量、全文与图检索，支持由 LLM 驱动的记忆抽取 通过 Python SDK、CLI（`pmem`）、HTTP API Server（含 Dashboard）或 MCP Server 接入时共用同一套 `.env`；完整选项见 [.env.example](.env.example) 与 [配置指南](docs/guides/0003-configuration.md)。 -> **动态：** [OpenClaw](https://github.com/openclaw-ai/openclaw) 可通过插件 [memory-powermem](https://github.com/ob-labs/memory-powermem) 使用 PowerMem 作为长期记忆（`openclaw plugins install memory-powermem`）。 +> **动态：** [OpenClaw](https://github.com/openclaw/openclaw) 可通过插件 [memory-powermem](https://github.com/ob-labs/memory-powermem) 使用 PowerMem 作为长期记忆（`openclaw plugins install memory-powermem`）。 ## 快速开始 @@ -92,8 +92,8 @@ for result in results.get("results", []): ## 示例 - [场景与 Notebook](docs/examples/overview.md) — 按用例的说明与笔记本（基础、多模态、遗忘曲线等） -- [LangChain 示例](examples/langchain/README.md) — 医疗支持机器人 -- [LangGraph 示例](examples/langgraph/README.md) — 客服机器人 +- [LangChain 示例](examples/langchain/README.md) — 医疗支持机器人（LangChain + PowerMem + OceanBase） +- [LangGraph 示例](examples/langgraph/README.md) — 客服机器人（LangGraph + PowerMem + OceanBase） ## 版本要点 diff --git a/README_JP.md b/README_JP.md index 679611e..06f24a3 100644 --- a/README_JP.md +++ b/README_JP.md @@ -14,7 +14,7 @@ PowerMem はベクトル・全文・グラフ検索に加え、LLM によるメ Python SDK、CLI（`pmem`）、HTTP API Server（Dashboard 付き）、MCP Server は同一の `.env` を共有します。[.env.example](.env.example) と [設定ガイド](docs/guides/0003-configuration.md) を参照してください。 -> **ニュース:** [OpenClaw](https://github.com/openclaw-ai/openclaw) はプラグイン [memory-powermem](https://github.com/ob-labs/memory-powermem) により PowerMem を長期メモリとして利用できます（`openclaw plugins install memory-powermem`）。 +> **ニュース:** [OpenClaw](https://github.com/openclaw/openclaw) はプラグイン [memory-powermem](https://github.com/ob-labs/memory-powermem) により PowerMem を長期メモリとして利用できます（`openclaw plugins install memory-powermem`）。 ## クイックスタート @@ -92,8 +92,8 @@ for result in results.get("results", []): ## サンプル - [シナリオと Notebook](docs/examples/overview.md) — ユースケース別の手順とノート（基本、マルチモーダル、忘却曲線など） -- [LangChain サンプル](examples/langchain/README.md) — 医療サポートチャットボット -- [LangGraph サンプル](examples/langgraph/README.md) — カスタマーサービスボット +- [LangChain サンプル](examples/langchain/README.md) — 医療サポートチャットボット（LangChain + PowerMem + OceanBase） +- [LangGraph サンプル](examples/langgraph/README.md) — カスタマーサービスボット（LangGraph + PowerMem + OceanBase） ## リリースハイライト