快速开始

两条路径。60 秒路径不需要 API Key；5 分钟路径额外开启 LLM 巩固。

路径 A — 60 秒，无需 API Key

写入和混合检索完全离线运行（基于内置的本地 Embedding 模型）。

1. 安装

pipx install hebb-mind

需要 Python >= 3.10。SQLite 内置，无需外部数据库。

还没装 pipx？ 它是 Python CLI 工具的标准安装器：隔离 venv、自动配置 PATH、兼容 PEP 668。一次性装好就行：

# macOS（Homebrew）
brew install pipx && pipx ensurepath

# Linux — Debian / Ubuntu 23.04+
sudo apt install pipx && pipx ensurepath

# Linux — Fedora
sudo dnf install pipx && pipx ensurepath

# Windows / 其他装了 Python 3.10+ 的环境
python -m pip install --user pipx && python -m pipx ensurepath

新开一个终端让 PATH 生效，再回来跑 pipx install hebb-mind。

更习惯 pip？也可以：python -m venv .venv && source .venv/bin/activate && pip install -U hebb-mind —— hebb 自动落在 venv 的 PATH 上。

2. Setup

hebb setup

在工作目录下生成 hebb.json 与 hebb.db，根据系统语言选择 Embedding 模型，并预下载。language 与 region 是独立参数：

hebb setup --language en --region cn      # 英文模型，国内镜像
hebb setup --language zh --region global  # 多语言模型，HuggingFace 官方源

3. 安装后台服务

hebb service install

该命令把 Hebb Mind 注册为系统级服务并立即启动：macOS 用 launchd，Linux 用 systemd，Windows 用任务计划程序。默认是用户级安装，不需要 sudo 或管理员权限；如需系统级常驻，请加 --scope system。

打开 http://localhost:8321/ 进入 Web 控制台，或访问 http://localhost:8321/docs 查看 OpenAPI 页。运行 hebb config get workspace 可查看数据存放位置。

4. 写入与搜索

curl -X POST http://localhost:8321/api/v1/memories \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "用户偏好深色模式与紧凑布局",
    "tags": ["preference", "ui"],
    "importance_score": 7.5
  }'

curl -X POST http://localhost:8321/api/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "UI 偏好", "top_k": 5}'

到这一步，向量 + 关键词 + 标签图谱的三路混合检索已完全在本地运行，无任何外部调用。

路径 B — 5 分钟，启用 LLM 巩固

巩固、冲突解决、标签提取需要 LLM。未配置 llm_api_key 时，相关接口会静默返回空结果（v0.1.1 已知问题，详见 Troubleshooting）。

1. 配置 LLM

hebb config set llm_api_key sk-your-key
hebb config set llm_model openai/gpt-4o-mini

通过 LiteLLM 切换提供商：

# Anthropic
hebb config set llm_model anthropic/claude-3-haiku-20240307

# 通义千问 / GLM / Kimi（OpenAI 兼容端点）
hebb config set llm_base_url https://dashscope.aliyuncs.com/compatible-mode/v1
hebb config set llm_model openai/qwen-plus

2. 触发巩固

curl -X POST http://localhost:8321/api/v1/admin/consolidate

或等待每日 18:00 的定时任务。巩固期间提取的标签会写入知识图谱，可通过 GET /api/v1/graph/tags 查看。

30 秒 Python SDK

from hebb import HebbMind

mem = HebbMind()  # 使用 ~/.hebb/hebb.json

mem.add("用户偏好深色模式", tags=["preference", "ui"], importance=7.5)

for hit in mem.search("UI 偏好", top_k=5):
    print(hit.score, hit.content)

服务生命周期

Hebb Mind 统一以操作系统后台服务的方式运行，常用命令：

hebb service install     # 注册并启动（launchd / systemd / 任务计划程序）
hebb status      # 查看是否安装与是否运行
hebb service restart     # 原地重启
hebb service stop        # 停止但保留安装
hebb service uninstall   # 从系统中移除

所有 service 子命令都支持 --scope user（默认，无需权限提升）或 --scope system（需要 sudo / 管理员；系统级开机自启）。

Docker 部署见 存储后端。

MCP 与编辑器集成

hebb claude-code install --scope user      # Claude Code：hooks 自动记忆
hebb codex install --scope user   # Codex：MCP 记忆工具
codex mcp list                           # 验证

通用 MCP 客户端（Cursor 等）：

{
  "mcpServers": {
    "hebb": { "command": "hebb-mcp" }
  }
}

详见：MCP 集成 · Claude Code 集成 · Codex 集成

下一步

• 配置 — 完整字段说明
• 记忆生命周期 — 系统核心机制
• Benchmarks — LoCoMo / LongMemEval 结果
• API 文档 — 完整 API 参考