From fde88aeb6d1721fdfffcbcd35a07a896ac1212e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=BF=9E=E5=AD=9F?= Date: Thu, 30 Jul 2026 15:03:37 +0800 Subject: [PATCH] docs(integrations): add 10-line recipes for LlamaIndex/CrewAI/AutoGen/LangGraph MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #29 Add copy-paste "connect in 10 lines" guide pages (EN + zh mirror) for LlamaIndex, CrewAI, AutoGen, and LangGraph. Each snippet wraps an existing surface (MCP stdio server hebb-mcp, or REST API on localhost:8321) — no new runtime library code. Wire the new page into the VitePress sidebar (EN + zh via the shared guideSidebar), README integrations area, and examples/README. Co-Authored-By: Claude Sonnet 5 --- README.md | 2 + examples/README.md | 4 + repo_pages/.vitepress/config.mts | 1 + repo_pages/guide/framework-integrations.md | 209 ++++++++++++++++++ repo_pages/zh/guide/framework-integrations.md | 201 +++++++++++++++++ 5 files changed, 417 insertions(+) create mode 100644 repo_pages/guide/framework-integrations.md create mode 100644 repo_pages/zh/guide/framework-integrations.md diff --git a/README.md b/README.md index 5524178..13c1773 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,8 @@ hebb agent-sync sync --dry-run # Preview historical session import Docker, one-line install, and source build: [Installation Guide](https://afx-team.github.io/hebb-mind/guide/installation.html). +Using Hebb Mind from **LlamaIndex / CrewAI / AutoGen / LangGraph**? See the [Python Framework Integration](https://afx-team.github.io/hebb-mind/guide/framework-integrations.html) recipes (~10 lines each, copy-paste runnable). + ## 30-second Python SDK ```python diff --git a/examples/README.md b/examples/README.md index 11b3931..686b528 100644 --- a/examples/README.md +++ b/examples/README.md @@ -17,6 +17,8 @@ Want a chatbot that remembers across runs? ──→ 02_persistent_chat.py Want your AI coding agent to use Hebb Mind? ──→ 03_mcp_quickstart.md Want to see (or reproduce) benchmark numbers? ──→ 04_benchmarks_locomo.md Want to plug Hebb Mind into LangChain? ──→ 05_langchain_adapter.py (WIP) +Want to wire Hebb Mind into LlamaIndex / CrewAI / AutoGen / LangGraph? + ──→ Python Framework Integration guide ``` ## Table of contents @@ -81,4 +83,6 @@ python examples/02_persistent_chat.py The audit (`reports/analysis/audit-examples.md`) lists the next examples we'd love to see: LangChain (#5 here is a starting skeleton), LlamaIndex, OpenAI Agents SDK, CrewAI, and a Jupyter walkthrough of the consolidation lifecycle. +Copy-paste recipes for LlamaIndex / CrewAI / AutoGen / LangGraph live in the +[Python Framework Integration guide](https://afx-team.github.io/hebb-mind/guide/framework-integrations.html); PRs welcome — please keep each example self-contained and under ~200 lines. diff --git a/repo_pages/.vitepress/config.mts b/repo_pages/.vitepress/config.mts index 6550894..6982bb4 100644 --- a/repo_pages/.vitepress/config.mts +++ b/repo_pages/.vitepress/config.mts @@ -316,6 +316,7 @@ function guideSidebar(prefix = '') { { text: prefix ? 'Agent 同步' : 'Agent Sync', link: `${prefix}/guide/agent-sync` }, { text: prefix ? '导入 Agent 记忆' : 'Import Agent Memory', link: `${prefix}/guide/import` }, { text: prefix ? 'MCP 集成' : 'MCP Integration', link: `${prefix}/guide/mcp-integration` }, + { text: prefix ? 'Python 框架集成' : 'Python Frameworks', link: `${prefix}/guide/framework-integrations` }, { text: prefix ? 'Web 控制台' : 'Web Console', link: `${prefix}/guide/web-console` }, { text: prefix ? '从其他系统迁移' : 'Migration from mem0 / Letta / Zep', link: `${prefix}/guide/migration` }, ], diff --git a/repo_pages/guide/framework-integrations.md b/repo_pages/guide/framework-integrations.md new file mode 100644 index 0000000..11be7a5 --- /dev/null +++ b/repo_pages/guide/framework-integrations.md @@ -0,0 +1,209 @@ +--- +description: "Connect LlamaIndex, CrewAI, AutoGen, and LangGraph to Hebb Mind in ~10 lines — write and recall long-term agent memory over the MCP server or REST API." +--- + +# Use Hebb Mind from a Python Agent Framework + +Hebb Mind ships two surfaces any Python agent framework can talk to today — no +native adapter package required: + +- **MCP stdio server** (`hebb-mcp`) exposing `write_memory` / `search_memory` / + `consolidate` / `ingest_conversation` (see [MCP Integration](./mcp-integration.md)). +- **REST API** at `http://localhost:8321` — `POST /api/v1/search` with + `{"query": ..., "top_k": ...}` and `POST /api/v1/memories`. + +Each snippet below wraps one of these surfaces for a popular framework. They are +copy-paste runnable against a locally running Hebb Mind service. + +::: tip Start the service first +Every snippet assumes the Hebb Mind background service is reachable on +`http://localhost:8321`. If you haven't installed it yet: + +```bash +pipx install hebb-mind +hebb setup # first time only — downloads a small embedding model +hebb service install # registers the OS background service (no admin needed) +``` + +Verify with `curl -X POST http://localhost:8321/api/v1/search -H 'Content-Type: application/json' -d '{"query":"ping","top_k":1}'`. +::: + +::: tip Use the absolute path to `hebb-mcp` +The MCP snippets show `command="hebb-mcp"` for brevity. If your framework's MCP +client doesn't inherit your shell `PATH`, run `which hebb-mcp` and pass the +**absolute path** instead — otherwise the server silently fails to start. +::: + +--- + +## LlamaIndex + +LlamaIndex talks to MCP servers through `llama-index-tools-mcp`. We start the +`hebb-mcp` stdio server, load its tools, and hand them to an agent that can now +write and recall memories. + +```bash +pip install llama-index llama-index-tools-mcp llama-index-llms-openai +``` + +```python +import asyncio +from llama_index.tools.mcp import McpToolSpec, BasicMCPClient + +async def main(): + # 1. Connect to the hebb-mcp stdio server (use `which hebb-mcp` for the absolute path) + client = BasicMCPClient(command_or_url="hebb-mcp") + tools = await McpToolSpec(client).to_tool_list_async() # -> [write_memory, search_memory, ...] + search = next(t for t in tools if t.metadata.name == "search_memory") + + # 2. Write a memory, then recall it through the loaded tool + write = next(t for t in tools if t.metadata.name == "write_memory") + print(await write.acall(content="User prefers dark mode and compact layout", + tags=["preference", "ui"], importance=7.5)) + print(await search.acall(query="UI preferences", top_k=5)) + +asyncio.run(main()) +``` + +Prefer REST? `POST /api/v1/search` returns `{"results": [{"memory": {...}, "score": ...}]}` — +wrap it in a custom `BaseRetriever` and plug into any `RetrieverQueryEngine`. + +--- + +## CrewAI + +CrewAI loads MCP tools via `crewai-tools`' `MCPServerAdapter`. We spin up the +`hebb-mcp` stdio server, expose its tools, and assign them to an agent. + +```bash +pip install crewai crewai-tools +``` + +```python +from crewai import Agent, Task, Crew +from crewai.tools import MCPServerAdapter + +# 1. Start the hebb-mcp stdio server and load its tools +with MCPServerAdapter({"command": "hebb-mcp"}) as tools: # -> [write_memory, search_memory, ...] + recall = next(t for t in tools if t.name == "search_memory") + + # 2. Give an agent the recall tool and run a one-step task + agent = Agent(role="Memory Assistant", goal="Recall stored user preferences", + backstory="A helpful agent backed by Hebb Mind long-term memory.", + tools=[recall], llm="gpt-4o-mini") + crew = Crew(agents=[agent], tasks=[Task(description="What UI does the user prefer?", + expected_output="A short sentence.", agent=agent)]) + print(crew.kickoff()) +``` + +Prefer REST? Hit `POST /api/v1/memories` / `POST /api/v1/search` with `requests` +inside a `crewai.tools.BaseTool` subclass. + +--- + +## AutoGen + +AutoGen **0.4+** (the `autogen-agentchat` / `autogen-ext[mcp]` packages) loads +MCP tools with `mcp_server_tools`. We connect to `hebb-mcp` over stdio and give +the tools to a `ToolUseAssistant`. + +```bash +pip install "autogen-agentchat==0.4.*" "autogen-ext[openai,mcp]" +``` + +```python +import asyncio +from autogen_agentchat.agents import AssistantAgent +from autogen_ext.models.openai import OpenAIChatCompletionClient +from autogen_ext.tools.mcp import StdioServerParams, mcp_server_tools + +async def main(): + # 1. Discover the hebb-mcp tools over stdio + params = StdioServerParams(command="hebb-mcp", args=[], read_transport="stdio", write_transport="stdio") + tools = await mcp_server_tools(params) # -> [write_memory, search_memory, ...] + + # 2. Attach them to an agent and run a recall task + agent = AssistantAgent("memory", model_client=OpenAIChatCompletionClient(model="gpt-4o-mini"), + tools=tools, reflect_on_tool_use=True) + print(await agent.run(task="Search Hebb Mind for the user's UI preferences.")) + +asyncio.run(main()) +``` + +::: warning Pin the AutoGen version +AutoGen 0.2 (legacy) and 0.4+ have incompatible APIs. The snippet above targets +**0.4+**; on 0.2 use `autogen.ConversableAgent` with a custom `register_function` +that calls the REST API instead. +::: + +Prefer REST? `POST /api/v1/search` works directly — wrap it in an AutoGen tool +function (`async def search_hebb(query: str) -> str`). + +--- + +## LangGraph + +LangGraph loads MCP tools through `langchain-mcp-adapters`. We start `hebb-mcp` +over stdio, load the tools, and bind them into a ReAct-style graph node. + +```bash +pip install langgraph langchain-mcp-adapters langchain-openai +``` + +```python +import asyncio +from langchain_mcp_adapters.client import MultiServerMCPClient + +async def main(): + # 1. Load hebb-mcp tools from the stdio server + client = MultiServerMCPClient({"hebb": {"command": "hebb-mcp", "transport": "stdio"}}) + tools = await client.get_tools() # -> [write_memory, search_memory, ...] + + # 2. Bind them to a chat model and do a write + recall round-trip + from langchain_openai import ChatOpenAI + llm = ChatOpenAI(model="gpt-4o-mini").bind_tools(tools) + write = next(t for t in tools if t.name == "write_memory") + print(await write.ainvoke({"content": "User prefers dark mode", "tags": ["ui"], "importance": 7.5})) + print(await llm.ainvoke("What UI does the user prefer? Use your Hebb Mind tool.")) + +asyncio.run(main()) +``` + +::: tip Don't extend the WIP skeleton +`examples/05_langchain_adapter.py` is a `NotImplementedError` skeleton for a +native `BaseRetriever` / `BaseChatMessageHistory`. This page is the low-cost +"paste a snippet" bridge — a native adapter is a separate follow-up. +::: + +--- + +## Which surface should I pick? + +| Framework | Lowest-friction path | Why | +|-----------|---------------------|-----| +| LlamaIndex | MCP (`MCPClient`) | First-class `MCPClient` + tool → agent flow | +| CrewAI | MCP (`MCPServerAdapter`) | `tools=[...]` on `Agent` is idiomatic | +| AutoGen 0.4+ | MCP (`mcp_server_tools`) | `StdioServerParams` is the supported loader | +| LangGraph | MCP (`langchain-mcp-adapters`) | `get_tools()` binds straight into graph nodes | + +Reach for the **REST API** only when a framework has no MCP adapter, or when you +need the full response shape (`results` + graph-expanded `related`) that the MCP +tool collapses into a text summary. + +## How it works + +``` +LlamaIndex / CrewAI / AutoGen / LangGraph + │ (stdio) + v + hebb-mcp (MCP server) ──or── httpx/requests ──> REST API + │ (HTTP) │ (port 8321) + v v + hebb service (REST API on 8321, OS background service) + │ + Storage / Embedder / Searcher / Tag graph +``` + +The MCP server is a thin wrapper translating tool calls into HTTP requests to +the running Hebb Mind service — so both paths hit the same storage, embedding, +and hybrid-search engine. \ No newline at end of file diff --git a/repo_pages/zh/guide/framework-integrations.md b/repo_pages/zh/guide/framework-integrations.md new file mode 100644 index 0000000..465f4e9 --- /dev/null +++ b/repo_pages/zh/guide/framework-integrations.md @@ -0,0 +1,201 @@ +--- +description: "用约 10 行代码把 LlamaIndex、CrewAI、AutoGen、LangGraph 接入 Hebb Mind —— 通过 MCP 服务或 REST API 写入与召回智能体长期记忆。" +--- + +# 在 Python Agent 框架中使用 Hebb Mind + +Hebb Mind 目前对外提供两套接口，任何 Python agent 框架都能直接调用，无需安装原生适配包： + +- **MCP stdio 服务**（`hebb-mcp`），暴露 `write_memory` / `search_memory` / + `consolidate` / `ingest_conversation` 四个工具（见 [MCP 集成](./mcp-integration.md)）。 +- **REST API**，地址 `http://localhost:8321` —— `POST /api/v1/search`（body + `{"query": ..., "top_k": ...}`）与 `POST /api/v1/memories`。 + +下面每个框架给一段可直接复制运行的示例，均假设本地 Hebb Mind 服务已在 +`http://localhost:8321` 运行。 + +::: tip 先把服务跑起来 +每个示例都假设 Hebb Mind 后台服务在 `http://localhost:8321` 可达。如果还没装： + +```bash +pipx install hebb-mind +hebb setup # 首次使用 —— 下载一个小型 embedding 模型 +hebb service install # 注册后台服务（默认用户级，无需管理员权限） +``` + +用 `curl -X POST http://localhost:8321/api/v1/search -H 'Content-Type: application/json' -d '{"query":"ping","top_k":1}'` 验证是否通。 +::: + +::: tip 关于 `command` 路径 +下面的 MCP 示例为简洁起见写的是裸 `hebb-mcp`。如果你的框架 MCP 客户端不继承 shell 的 +`PATH`，请用 `which hebb-mcp` 查出**绝对路径**再填入 —— 否则服务会静默启动失败。 +::: + +--- + +## LlamaIndex + +LlamaIndex 通过 `llama-index-tools-mcp` 连接 MCP 服务。我们启动 `hebb-mcp` stdio 服务， +加载其工具，然后交给一个能写入与召回记忆的 agent。 + +```bash +pip install llama-index llama-index-tools-mcp llama-index-llms-openai +``` + +```python +import asyncio +from llama_index.tools.mcp import McpToolSpec, BasicMCPClient + +async def main(): + # 1. 连接 hebb-mcp stdio 服务（用 `which hebb-mcp` 取绝对路径） + client = BasicMCPClient(command_or_url="hebb-mcp") + tools = await McpToolSpec(client).to_tool_list_async() # -> [write_memory, search_memory, ...] + search = next(t for t in tools if t.metadata.name == "search_memory") + + # 2. 写一条记忆，再通过加载的工具召回 + write = next(t for t in tools if t.metadata.name == "write_memory") + print(await write.acall(content="用户偏好深色模式与紧凑布局", + tags=["preference", "ui"], importance=7.5)) + print(await search.acall(query="UI 偏好", top_k=5)) + +asyncio.run(main()) +``` + +想用 REST？`POST /api/v1/search` 返回 `{"results": [{"memory": {...}, "score": ...}]}` —— +包成一个自定义 `BaseRetriever`，即可接入任意 `RetrieverQueryEngine`。 + +--- + +## CrewAI + +CrewAI 通过 `crewai-tools` 的 `MCPServerAdapter` 加载 MCP 工具。我们拉起 `hebb-mcp` stdio +服务，暴露其工具，再分配给一个 agent。 + +```bash +pip install crewai crewai-tools +``` + +```python +from crewai import Agent, Task, Crew +from crewai.tools import MCPServerAdapter + +# 1. 启动 hebb-mcp stdio 服务并加载其工具 +with MCPServerAdapter({"command": "hebb-mcp"}) as tools: # -> [write_memory, search_memory, ...] + recall = next(t for t in tools if t.name == "search_memory") + + # 2. 把召回工具交给 agent，跑一个单步任务 + agent = Agent(role="记忆助手", goal="召回已存储的用户偏好", + backstory="一个由 Hebb Mind 长期记忆支撑的助手。", + tools=[recall], llm="gpt-4o-mini") + crew = Crew(agents=[agent], tasks=[Task(description="用户偏好什么 UI？", + expected_output="一句话简述。", agent=agent)]) + print(crew.kickoff()) +``` + +想用 REST？用 `requests` 直接打 `POST /api/v1/memories` / `POST /api/v1/search`，包在一个 +`crewai.tools.BaseTool` 子类里即可。 + +--- + +## AutoGen + +AutoGen **0.4+**（`autogen-agentchat` / `autogen-ext[mcp]` 包）通过 `mcp_server_tools` 加载 +MCP 工具。我们经 stdio 连接 `hebb-mcp`，把工具交给一个 `ToolUseAssistant`。 + +```bash +pip install "autogen-agentchat==0.4.*" "autogen-ext[openai,mcp]" +``` + +```python +import asyncio +from autogen_agentchat.agents import AssistantAgent +from autogen_ext.models.openai import OpenAIChatCompletionClient +from autogen_ext.tools.mcp import StdioServerParams, mcp_server_tools + +async def main(): + # 1. 经 stdio 发现 hebb-mcp 的工具 + params = StdioServerParams(command="hebb-mcp", args=[], read_transport="stdio", write_transport="stdio") + tools = await mcp_server_tools(params) # -> [write_memory, search_memory, ...] + + # 2. 把工具挂到 agent 上，跑一个召回任务 + agent = AssistantAgent("memory", model_client=OpenAIChatCompletionClient(model="gpt-4o-mini"), + tools=tools, reflect_on_tool_use=True) + print(await agent.run(task="在 Hebb Mind 里搜索用户的 UI 偏好。")) + +asyncio.run(main()) +``` + +::: warning 锁定 AutoGen 版本 +AutoGen 0.2（旧版）与 0.4+ 的 API 不兼容。上面的示例面向 **0.4+**；若用 0.2，请改用 +`autogen.ConversableAgent`，通过 `register_function` 注册一个调用 REST API 的函数。 +::: + +想用 REST？`POST /api/v1/search` 可直接调用 —— 包成一个 AutoGen 工具函数 +（`async def search_hebb(query: str) -> str`）即可。 + +--- + +## LangGraph + +LangGraph 通过 `langchain-mcp-adapters` 加载 MCP 工具。我们经 stdio 启动 `hebb-mcp`，加载 +工具，再把它们绑定到一个 ReAct 风格的图节点。 + +```bash +pip install langgraph langchain-mcp-adapters langchain-openai +``` + +```python +import asyncio +from langchain_mcp_adapters.client import MultiServerMCPClient + +async def main(): + # 1. 从 stdio 服务加载 hebb-mcp 工具 + client = MultiServerMCPClient({"hebb": {"command": "hebb-mcp", "transport": "stdio"}}) + tools = await client.get_tools() # -> [write_memory, search_memory, ...] + + # 2. 绑定到 chat 模型，做一次写入 + 召回往返 + from langchain_openai import ChatOpenAI + llm = ChatOpenAI(model="gpt-4o-mini").bind_tools(tools) + write = next(t for t in tools if t.name == "write_memory") + print(await write.ainvoke({"content": "用户偏好深色模式", "tags": ["ui"], "importance": 7.5})) + print(await llm.ainvoke("用户偏好什么 UI？用你的 Hebb Mind 工具查一下。")) + +asyncio.run(main()) +``` + +::: tip 不要去补那个 WIP 骨架 +`examples/05_langchain_adapter.py` 是一个 `NotImplementedError` 骨架，目标是原生 +`BaseRetriever` / `BaseChatMessageHistory`。本页是低成本的"复制即用"过渡桥 —— 原生适配器是 +独立的后续任务。 +::: + +--- + +## 该选哪套接口？ + +| 框架 | 摩擦最低的路径 | 原因 | +|------|--------------|------| +| LlamaIndex | MCP（`MCPClient`） | 一等公民 `MCPClient` + 工具 → agent 流程 | +| CrewAI | MCP（`MCPServerAdapter`） | `Agent` 的 `tools=[...]` 是惯用写法 | +| AutoGen 0.4+ | MCP（`mcp_server_tools`） | `StdioServerParams` 是受支持的加载器 | +| LangGraph | MCP（`langchain-mcp-adapters`） | `get_tools()` 可直接绑进图节点 | + +只有当一个框架没有 MCP 适配器、或你需要 MCP 工具折叠成文本摘要之前的完整响应结构 +（`results` + 图谱扩展的 `related`）时，才改用 **REST API**。 + +## 工作原理 + +``` +LlamaIndex / CrewAI / AutoGen / LangGraph + │ (stdio) + v + hebb-mcp（MCP 服务） ──或── httpx/requests ──> REST API + │ (HTTP) │ (端口 8321) + v v + hebb 服务（端口 8321 的 REST API，由 OS 后台服务运行） + │ + 存储 / Embedding / 检索器 / 标签图谱 +``` + +MCP 服务只是一个薄封装，把工具调用翻译成对 Hebb Mind 服务的 HTTP 请求 —— 所以两条路径 +最终都命中同一套存储、embedding 与混合检索引擎。 \ No newline at end of file