# https://github.com/agentkitai/lore 项目说明书

生成时间：2026-06-21 20:48:11 UTC

## 目录

- [项目概述与系统架构](#page-1)
- [记忆操作、知识图谱与 v0.7.0 Living Archive](#page-2)
- [多代理集成、MCP 与部署](#page-3)
- [运维、可扩展性与企业级能力](#page-4)

<a id='page-1'></a>

## 项目概述与系统架构

### 相关页面

相关主题：[记忆操作、知识图谱与 v0.7.0 Living Archive](#page-2), [多代理集成、MCP 与部署](#page-3), [运维、可扩展性与企业级能力](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/agentkitai/lore/blob/main/README.md)
- [ts/README.md](https://github.com/agentkitai/lore/blob/main/ts/README.md)
- [src/lore/cli/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/__init__.py)
- [src/lore/cli/_helpers.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/_helpers.py)
- [src/lore/cli/commands/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/__init__.py)
- [src/lore/cli/commands/graph.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/graph.py)
- [src/lore/cli/commands/misc.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/misc.py)
- [src/lore/cli/commands/observations.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/observations.py)
- [src/lore/cli/commands/keys.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/keys.py)
- [src/lore/cli/commands/_project.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/_project.py)
- [src/lore/cli/formatters.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/formatters.py)
- [src/lore/server/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/__init__.py)
- [src/lore/server/routes/memories.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/memories.py)
- [src/lore/server/routes/topics.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/topics.py)
- [src/lore/server/routes/sharing.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/sharing.py)

</details>

# 项目概述与系统架构

## 项目定位与核心能力

Lore 是一个面向多代理（multi-agent）场景的**跨代理记忆 SDK 与云服务平台**，目标是让任意 AI 代理能够持久化存储、语义检索、结构化整理并与其他代理共享记忆。`README.md` 中明确把项目描述为 "Lore SDK — cross-agent memory CLI"，并提供了从 `recall()`、知识图谱查询到富化（enrichment）、快照、策略、审计的完整能力矩阵。

在 v0.7.0 "Living Archive" 版本中，社区公告重点介绍了三个新特性：

- **On This Day**（历史回顾）
- **Verbatim Recall**（逐字回溯）
- **Temporal Filters**（时间维度过滤器）

社区资料显示该版本全部 1516 项单元测试通过。资料来源：[README.md:1-50]() [v0.7.0 Release](https://github.com/agentkitai/lore/releases/tag/v0.7.0)。

Lore 同时提供 Python SDK、TypeScript SDK（参见 `ts/README.md`）以及一个基于 FastAPI 的 Cloud Server，并通过 CLI、REST API、MCP（Model Context Protocol）三种方式对外暴露能力。环境变量 `LORE_API_URL` / `LORE_API_KEY` 默认指向本地 `http://localhost:8765`，便于本地 Docker Compose 启动。资料来源：[README.md: environment-variables]() [ts/README.md: env-vars]()。

## 系统架构总览

Lore 的整体架构可以划分为四层：**Python/TypeScript SDK 层 → CLI 命令层 → FastAPI Server 层 → 持久化与知识图谱层**。下图为各层及关键模块的依赖关系。

```mermaid
flowchart TB
    subgraph SDK["SDK 层"]
        PySDK["lore (Python SDK)"]
        TSSDK["lore-sdk (TypeScript)"]
    end

    subgraph CLI["CLI 命令层 (src/lore/cli)"]
        Entry["cli/__init__.py main()"]
        Helpers["cli/_helpers.py"]
        CmdRegistry["cli/commands/__init__.py"]
        CmdGraph["commands/graph.py"]
        CmdMisc["commands/misc.py"]
        CmdObs["commands/observations.py"]
        CmdKeys["commands/keys.py"]
        CmdProj["commands/_project.py"]
    end

    subgraph Server["FastAPI Server (src/lore/server)"]
        SRoot["server/__init__.py"]
        RMem["routes/memories.py"]
        RTop["routes/topics.py"]
        RShare["routes/sharing.py"]
        Auth["server/auth"]
        Store["server/db.get_store"]
    end

    subgraph Persist["持久化与图谱层"]
        Store2["lore.persistence.Store"]
        Svc["lore.services (topics, sharing)"]
        KG["knowledge graph + claude CLI"]
    end

    PySDK --> Entry
    TSSDK --> Entry
    Entry --> CmdRegistry
    CmdRegistry --> CmdGraph
    CmdRegistry --> CmdMisc
    CmdRegistry --> CmdObs
    CmdRegistry --> CmdKeys
    Entry --> Helpers
    Helpers --> PySDK
    CmdProj --> Entry
    PySDK --> Store2
    PySDK --> KG
    SRoot --> RMem
    SRoot --> RTop
    SRoot --> RShare
    RMem --> Store
    RTop --> Svc
    RShare --> Svc
    Store --> Store2
```

**SDK 层**：`lore` 主模块对外提供 `remember()`、`recall()`、`classify()`、`get_facts()`、`topic_detail()` 等同步 API，并对应提供异步版本。TypeScript SDK 通过 `lore.remember`、`lore.recall` 等 promise 接口与 Python SDK 保持一致语义。资料来源：[README.md: quick-start]() [ts/README.md: api]()。

**CLI 层**：`cli/__init__.py` 中的 `main()` 是统一入口，`build_parser()` 使用 `argparse` 注册所有子命令，并通过 `from lore.cli.commands import ...` 把命令分发给 `graph`、`misc`、`observations`、`keys` 等模块。CLI 共享逻辑放在 `_helpers.py`，例如 `_get_lore()` 根据 `OPENAI_API_KEY` 是否存在自动开启富化，并通过 `LORE_ENRICHMENT_MODEL`（默认 `gpt-4o-mini`）选择模型。资料来源：[src/lore/cli/__init__.py:1-80]() [src/lore/cli/_helpers.py:1-40]()。

**Server 层**：`src/lore/server/__init__.py` 标注为 "Lore Cloud Server — FastAPI application"。`routes/memories.py` 提供 `/v1/memories` 的 CRUD（更新/删除要求 `writer` 或 `admin` 角色）；`routes/topics.py` 暴露 `/v1/topics` 列表与详情查询；`routes/sharing.py` 暴露 `/v1/sharing` 的配置、人审、限流、统计等模型。所有路由通过 `Depends(get_auth_context)` 注入认证上下文，通过 `Depends(get_store)` 注入持久化 `Store`。资料来源：[src/lore/server/routes/memories.py:patch-delete]() [src/lore/server/routes/topics.py:1-60]() [src/lore/server/routes/sharing.py:1-60]()。

**持久化与图谱层**：底层 `lore.persistence.Store` 是被 CLI 与 Server 共享的协议实现；知识图谱启用时，`graph.py` 通过 `_entity_cache` 与 `_graph_traverser` 完成实体查找与关系遍历，富化与图谱抽取分别由 `OPENAI_API_KEY`/`LORE_ENRICHMENT_MODEL` 和本地 `claude` CLI 驱动。资料来源：[src/lore/cli/commands/graph.py:cmd_graph]() [README.md: env-vars]()。

## CLI 命令体系

`cli/commands/__init__.py` 是命令注册表，按职责拆分为多个子模块：

| 子模块 | 关注能力 | 关键导出 |
|--------|----------|----------|
| `capture` | 会话捕获、子代理抽取 | 由 `misc` 等调用 |
| `graph` | 图谱查询、实体、关系、主题、复核 | `cmd_graph`、`cmd_topics`、`cmd_entities` |
| `keys` | API Key 生命周期 | `cmd_keys_create/list/revoke` |
| `manage` | 记忆维护类命令 | 由 `__init__` 导入分发 |
| `migrate` | 存储迁移 | 同上 |
| `misc` | 分类、事实、冲突、回填、富化、重索引、On This Day、引导、整合、SLO、Profile、Policy、Workspace、审计、插件、建议等 | `cmd_classify`、`cmd_facts`、`cmd_conflicts`、`cmd_enrich`、`cmd_github_sync`、`cmd_on_this_day`、`cmd_workspace` 等 |
| `recall` | 召回与提示装配 | `cmd_recall`、`cmd_prompt` |
| `remember` | 写入记忆 | `cmd_remember` |
| `server` | 服务进程、MCP、UI | `cmd_serve`、`cmd_mcp`、`cmd_ui` |
| `snapshot` | 快照与合并 | `cmd_snapshot`、`cmd_consolidate` |

资料来源：[src/lore/cli/commands/__init__.py:1-30]() [src/lore/cli/commands/graph.py:1-30]() [src/lore/cli/commands/misc.py:1-40]() [src/lore/cli/commands/observations.py:cmd_observations]() [src/lore/cli/commands/keys.py:cmd_keys_create]()。

`observations.py` 提供 `lore observations {list|show <id>}` 的二级子命令，并把记忆的 `meta` 字段（事实、叙述、标签、捕获者、会话 ID 等）序列化为 JSON 输出。`keys.py` 通过 `_helpers._get_api_config()` 校验 `LORE_API_URL`/`LORE_API_KEY`，再调用 `_helpers._api_request()` 与 Server 的 `/v1/keys` 端点交互；根密钥通过 `--root` 标记下发 `is_root: true`。资料来源：[src/lore/cli/commands/observations.py:cmd_observations]() [src/lore/cli/commands/keys.py:cmd_keys_create]() [src/lore/cli/_helpers.py:_get_api_config]()。

CLI 与 Server 共享同一份 `Lore` 实例：`_get_lore()` 默认打开 `knowledge_graph=True`，因此诸如 `topics` 这类命令要求先执行 `lore config set knowledge_graph true` 才能输出结果。资料来源：[src/lore/cli/_helpers.py:_get_lore]() [src/lore/cli/commands/graph.py:cmd_topics]()。

## Server API 路由与鉴权

Server 路由统一前缀 `/v1`，鉴权通过 `get_auth_context` 注入 `AuthContext`，更敏感的写操作（更新、删除记忆）需要 `require_role("writer", "admin")`。`memories.py` 的 `update_memory` 在请求体没有任何字段时返回 422；找不到记忆抛出 `StoreNotFoundError`，被转换为 404。`topics.py` 在 `min_mentions` 与 `max_memories` 上设有边界校验（`ge=1, le=100/200`），主题未找到时返回 404。`sharing.py` 同时维护组织级共享配置、代理级白名单、拒绝列表（`DenyListRuleData`）以及审计事件（`AuditEventData`），模型字段使用 Pydantic `BaseModel`，限流默认 100 次/小时、流量告警阈值默认 1000。资料来源：[src/lore/server/routes/memories.py:patch-delete]() [src/lore/server/routes/topics.py:list_topics/get_topic_detail]() [src/lore/server/routes/sharing.py:1-80]()。

## 辅助模块

`cli/commands/_project.py` 单独承担"项目解析 + `<private>` 标签剥离"职责，通过 `lru_cache` 缓存 git remote URL 归一化结果（`github.com/user/repo`），并提供 `strip_private()` 在内容进入缓冲前完成脱敏，遵循"失败闭合"（unbalanced opening tag 一律剥离到字符串末尾，避免泄露）。`cli/formatters.py` 当前为空壳，作为未来抽离共享输出格式化函数（如 `cli_topics` 中重复出现的 `mention_count`、`created_at[:10]` 等模式）的占位。资料来源：[src/lore/cli/commands/_project.py:1-40]() [src/lore/cli/formatters.py:1-10]()。

## See Also

- 知识图谱与主题召回：参见 `src/lore/cli/commands/graph.py` 与 `src/lore/server/routes/topics.py`
- 富化与抽取管道：`LORE_ENRICHMENT_*` / `LORE_GRAPH_EXTRACTION_*` 环境变量（见 [README.md]()）
- TypeScript SDK API：`ts/README.md`
- v0.7.0 新特性公告：[release notes](https://github.com/agentkitai/lore/releases/tag/v0.7.0)

---

<a id='page-2'></a>

## 记忆操作、知识图谱与 v0.7.0 Living Archive

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [多代理集成、MCP 与部署](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/lore/cli/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/__init__.py)
- [src/lore/cli/_helpers.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/_helpers.py)
- [src/lore/cli/commands/graph.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/graph.py)
- [src/lore/cli/commands/misc.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/misc.py)
- [src/lore/cli/commands/observations.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/observations.py)
- [src/lore/cli/commands/keys.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/keys.py)
- [src/lore/server/routes/memories.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/memories.py)
- [src/lore/server/routes/topics.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/topics.py)
- [src/lore/server/routes/sharing.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/sharing.py)
- [README.md](https://github.com/agentkitai/lore/blob/main/README.md)
</details>

# 记忆操作、知识图谱与 v0.7.0 Living Archive

## 概述

Lore 是一个面向 AI Agent 的跨进程、跨 Agent 记忆 SDK（同时提供 Python 与 TypeScript 实现），核心目标是为多个 Agent 提供统一的"记忆层"。在 [README.md](https://github.com/agentkitai/lore/blob/main/README.md) 中描述了三大支柱：分层记忆（working / short / long）、可图谱化的实体/事实抽取、以及 Cloud Server 形态的多租户协作。v0.7.0 "Living Archive" 在该基础上引入了"On This Day"、"Verbatim Recall" 与 "Temporal Filters" 三个面向时间维度的特性，让长期记忆不再是"静态知识库"而是"会随时间被回看与检索的活动档案"。

下表概括 v0.7.0 引入的核心能力（资料来源：[README.md](https://github.com/agentkitai/lore/blob/main/README.md)）：

| 特性 | 作用 | 触发方式 |
|------|------|----------|
| On This Day | 回溯"历史上的今天"写入的记忆 | `lore on-this-day` / `GET /v1/timeline/on-this-day` |
| Verbatim Recall | 不做向量改写的精确字面检索 | `lore recall --verbatim` |
| Temporal Filters | 按时间窗口、相对时间、时区过滤 | `recall` / `on-this-day` / `timeline` 通用 `since`/`until` |

## 记忆操作（Memory Operations）

### CLI 层

CLI 是最常用的入口，定义在 [src/lore/cli/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/__init__.py) 中：`build_parser()` 构造 `lore` 主命令并挂载 `remember`、`recall`、`observations`、`snapshot`、`keys` 等子命令。命令处理函数分散在 `lore.cli.commands.*` 中：

- `cmd_remember` 负责把内容写入存储层，可指定 `--type`（lesson、fact、preference 等）与 `--tier`（working / short / long）。
- `cmd_recall` 接受查询字符串并返回语义召回结果；在 v0.7.0 中新增 `--verbatim` 标志以切换"Verbatim Recall"模式。
- `cmd_observations`（[src/lore/cli/commands/observations.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/observations.py)）提供 `observations list|show <id>` 子命令，用于查看 capture 子代理产生的结构化观察，其输出 JSON 含 `narrative`、`facts`、`tags`、`captured_by` 等字段。
- `cmd_on_this_day` 定义在 [src/lore/cli/commands/misc.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/misc.py)，调用 `lore.on_this_day()` 拉取与今天日期匹配的历史记忆。

CLI 通过 `lore.cli._helpers._get_lore()`（[src/lore/cli/_helpers.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/_helpers.py)）构造 SDK 实例：当检测到 `OPENAI_API_KEY` 时自动开启 enrichment，并默认开启 `knowledge_graph=True`，即 CLI 默认即可使用图谱能力。

### HTTP / Cloud Server 层

Cloud Server 由 FastAPI 提供，在 [src/lore/server/routes/memories.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/memories.py) 中实现了 `POST /v1/memories`、`PATCH /v1/memories/{id}`、`DELETE /v1/memories/{id}` 等 CRUD 接口，写操作要求 `writer` 或 `admin` 角色。返回的 `MemoryResponse` 模型包含 `scope` 字段（`project` / `org` / `agent`），用于支持后续的多租户工作区隔离。共享与审计相关的能力在 [src/lore/server/routes/sharing.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/sharing.py) 中通过 `SharingConfig`、`AgentSharingConfig` 模型提供。

## 知识图谱（Knowledge Graph）

Lore 的知识图谱由"实体抽取 → 关系构建 → 图谱遍历"三步组成，相关 CLI 命令集中在 [src/lore/cli/commands/graph.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/graph.py)：

- `cmd_topics` 列出被自动检测出的主题（实体），支持 `--entity-type` 与 `--min-mentions` 阈值过滤。`topic_detail(name)` 进一步返回该实体被提及的记忆列表。
- `cmd_graph` 输出图谱结构（节点 / 边），供调试或可视化使用。
- 使用图谱前需要显式开启：`lore config set knowledge_graph true`，否则 CLI 会提示"Topics require the knowledge graph"（资料来源：[src/lore/cli/commands/graph.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/graph.py)）。

Cloud Server 端的话题接口在 [src/lore/server/routes/topics.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/topics.py)：`GET /v1/topics` 支持 `entity_type`、`min_mentions`、`limit` 等查询参数；`GET /v1/topics/{name}` 返回该话题的详情。抽取默认由 `LORE_GRAPH_EXTRACTION_ENABLED` 控制：当本地 `claude` CLI 在 `PATH` 中时自动开启，并发与超时分别由 `LORE_GRAPH_EXTRACTION_CONCURRENCY`（默认 2）和 `LORE_GRAPH_EXTRACTION_TIMEOUT`（默认 30s）调节（资料来源：[README.md](https://github.com/agentkitai/lore/blob/main/README.md)）。

## v0.7.0 Living Archive 时间特性

v0.7.0 把"时间"提升为一等公民，使记忆系统从静态知识库演化为"Living Archive"。三个新特性的工作流如下图所示：

```mermaid
flowchart LR
    A[写入记忆] --> B[(持久化 Store)]
    B --> C{检索方式}
    C -- 向量相似 --> D[Semantic Recall]
    C -- 字面匹配 --> E[Verbatim Recall]
    C -- 历史今天 --> F[On This Day]
    C -- 时间窗口 --> G[Temporal Filters]
    D --> H[返回 RecallResult]
    E --> H
    F --> I[返回 TimelineEntry]
    G --> H
```

- **On This Day**：依据记忆的 `created_at` 字段做"同月同日"匹配，CLI 入口为 `lore on-this-day`（[src/lore/cli/commands/misc.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/misc.py)）。
- **Verbatim Recall**：跳过 embedding 改写，按原文/标签精确匹配，适合 ID、命令、错误码等字面场景。
- **Temporal Filters**：所有时间相关接口（recall、timeline、on-this-day）统一接受 `since` / `until` 参数，支持 ISO 时间戳与相对时间（如 `7d`）。

## 常见失败模式

- 未设置 `LORE_API_URL` 与 `LORE_API_KEY` 时，需要调用 Cloud Server 的命令（如 `keys create`、`keys list`，见 [src/lore/cli/commands/keys.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/keys.py)）会直接 `sys.exit(1)`，提示 "Error: --api-url or LORE_API_URL required"。
- 未启用 `knowledge_graph` 时调用图谱相关命令会得到"Run `lore config set knowledge_graph true`"的提示。
- `claude` CLI 不在 `PATH` 中时，`LORE_GRAPH_EXTRACTION_ENABLED` 自动为 `false`，实体抽取静默跳过——此时 `topics` 会返回空集。

## See Also

- [README.md](https://github.com/agentkitai/lore/blob/main/README.md) — 项目总览与环境变量
- [ts/README.md](https://github.com/agentkitai/lore/blob/main/ts/README.md) — TypeScript SDK 文档
- v0.7.0 发布说明：<https://github.com/agentkitai/lore/releases/tag/v0.7.0>

---

<a id='page-3'></a>

## 多代理集成、MCP 与部署

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [运维、可扩展性与企业级能力](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/agentkitai/lore/blob/main/README.md)
- [src/lore/cli/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/__init__.py)
- [src/lore/cli/_helpers.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/_helpers.py)
- [src/lore/cli/commands/server.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/server.py)
- [src/lore/cli/commands/misc.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/misc.py)
- [src/lore/server/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/__init__.py)
- [src/lore/server/routes/topics.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/topics.py)
- [src/lore/cli/commands/capture.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/capture.py)
- [src/lore/cli/commands/dream.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/dream.py)
- [ts/README.md](https://github.com/agentkitai/lore/blob/main/ts/README.md)
- [ts/package.json](https://github.com/agentkitai/lore/blob/main/ts/package.json)
</details>

# 多代理集成、MCP 与部署

## 概述

Lore 是一个跨代理记忆 SDK（Software Development Kit，软件开发工具包），其核心目标是让多个 AI 代理能够**共享、检索和回忆长期记忆**。本节聚焦于三条主线：让不同代理框架接入 Lore（多代理集成）、通过 Model Context Protocol（MCP，模型上下文协议）让宿主代理动态调用 Lore 工具、以及在不同环境中部署 Lore 服务。

在 v0.7.0「Living Archive」版本中，社区持续关注 On This Day、Verbatim Recall 与 Temporal Filters 等时间维度能力（详见 [v0.7.0 Release Notes](https://github.com/agentkitai/lore/releases/tag/v0.7.0)），这些功能同样需要借助下述集成与部署管道才能在生产环境中被多个代理同时访问。资料来源：[README.md]()。

## 多代理集成模式

Lore 提供 **Python SDK、TypeScript SDK 与 REST API** 三种接入形态，使任意代理框架（Claude Code、Cursor、自研代理等）都可以使用统一的记忆接口：

```python
# Python SDK 用法（src/lore/cli/_helpers.py 中的 _get_lore）
from lore import Lore
lore = Lore(enrichment=True, knowledge_graph=True)
lore.remember(content="...", type="lesson")
results = lore.recall("...")
```

```typescript
// TypeScript SDK 用法（ts/README.md）
import Lore from "lore-sdk";
const lore = new Lore({ /* ... */ });
await lore.remember({ content: "...", type: "lesson" });
```

CLI 命令 `lore setup` 进一步封装了针对主流代理客户端的初始化流程，例如：

```bash
lore setup claude-code --validate --test-connection
```

资料来源：[README.md]() 与 [src/lore/cli/_helpers.py]()。CLI 入口将子命令分派到 `server`、`misc`、`graph` 等模块，相关命令在 [src/lore/cli/__init__.py]() 中注册。

### 插件 SDK

为了让代理框架或组织自定义 Lore 行为，Lore 暴露了 **Plugin SDK**，支持五个生命周期钩子（`on_remember`、`on_recall`、`on_enrich`、`on_extract`、`on_score`），并通过 Python `entry_points` 自动发现。CLI 命令包括：

```bash
lore plugin create my-tagger
lore plugin list
lore plugin reload my-tagger
```

资料来源：[README.md]()。

## MCP 服务与 API 部署

Lore 提供 **MCP 服务**（`lore mcp`）和 **HTTP 服务**（`lore serve`），二者共享同一份持久化层与认证机制，详见 [src/lore/server/__init__.py]()。

```mermaid
flowchart LR
    A[Claude Code / Cursor] -->|MCP| M[lore mcp]
    B[自定义代理] -->|HTTP| S[lore serve]
    C[TS / Python SDK] -->|SDK| S
    M --> P[(Postgres + pgvector)]
    S --> P
    P --> T[/v1/memories /v1/topics/]
    T --> M
    T --> S
```

FastAPI 路由以 `/v1` 为前缀，例如 `GET /v1/topics/{name}` 由 [src/lore/server/routes/topics.py]() 提供；该模块注入 `AuthContext` 与 `Store` 依赖，是服务端权限与持久化衔接点。资料来源：[src/lore/server/routes/topics.py]()。

CLI 启动入口通过 `_helpers._get_lore` 统一构建 `Lore` 客户端实例，自动读取 `OPENAI_API_KEY` 等环境变量决定是否启用 enrichment 管道；远程访问则通过 `LORE_API_URL` 与 `LORE_API_KEY` 组合：

```python
# src/lore/cli/_helpers.py
api_url  = os.environ.get("LORE_API_URL")
api_key  = os.environ.get("LORE_API_KEY")
```

资料来源：[src/lore/cli/_helpers.py]()。

## 部署与环境配置

官方推荐使用 **Docker Compose** 一键启动 Postgres + pgvector + Lore 服务：

```bash
git clone https://github.com/agentkitai/lore.git
cd lore
docker compose up -d
```

服务默认监听 `http://localhost:8765`，对应环境变量 `LORE_API_URL=http://localhost:8765`。如需以 Python 包方式部署：

```bash
pip install lore-sdk[server]
```

常用环境变量整理如下：

| 变量 | 默认值 | 用途 |
|------|--------|------|
| `LORE_API_KEY` | — | API 认证密钥 |
| `LORE_API_URL` | `http://localhost:8765` | 远程服务端地址 |
| `LORE_PROJECT` | — | 默认项目作用域 |
| `LORE_ENRICHMENT_ENABLED` | `false` | 是否启用 LLM enrichment |
| `LORE_ENRICHMENT_MODEL` | `gpt-4o-mini` | enrichment 使用的模型 |
| `LORE_GRAPH_DEPTH` | `2` | 知识图谱默认遍历深度 |
| `LORE_GRAPH_EXTRACTION_ENABLED` | auto | 实体/事实抽取开关（依赖本地 `claude` CLI） |

资料来源：[README.md]()。需要注意的是，知识图谱抽取**使用本地 `claude` CLI**，而非 `OPENAI_API_KEY`；二者分别驱动独立的 enrichment 与 extraction 流水线。资料来源：[README.md]()。

### 性能基准

README 中给出的检索性能基线为：在 10K 记忆中 `recall()` 语义搜索小于 200 ms；启用知识图谱后端到端小于 500 ms；500 词文档 embedding 小于 200 ms。资料来源：[README.md]()。这些指标直接影响多代理场景下的并发部署规模与副本数量规划。

## See Also

- [README.md](https://github.com/agentkitai/lore/blob/main/README.md)
- [src/lore/cli/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/__init__.py)
- [v0.7.0 Living Archive Release Notes](https://github.com/agentkitai/lore/releases/tag/v0.7.0)

---

<a id='page-4'></a>

## 运维、可扩展性与企业级能力

### 相关页面

相关主题：[项目概述与系统架构](#page-1), [多代理集成、MCP 与部署](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/agentkitai/lore/blob/main/README.md)
- [src/lore/cli/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/__init__.py)
- [src/lore/cli/_helpers.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/_helpers.py)
- [src/lore/cli/commands/misc.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/misc.py)
- [src/lore/cli/commands/keys.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/keys.py)
- [src/lore/cli/commands/graph.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/graph.py)
- [src/lore/server/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/__init__.py)
- [src/lore/server/routes/topics.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/topics.py)
- [src/lore/server/routes/sharing.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/sharing.py)
- [ts/README.md](https://github.com/agentkitai/lore/blob/main/ts/README.md)
</details>

# 运维、可扩展性与企业级能力

Lore SDK 在跨 Agent 记忆核心之上，构建了一整套面向生产环境的**运维控制面**、**扩展点**与**企业治理能力**。截至 v0.7.0（Living Archive 发布，1516 个测试全部通过），这些能力通过 CLI 子命令、HTTP 路由与 Python 入口点三类接口暴露，使同一套代码既能本地原型，也能多租户上生产。

> 资料来源：[README.md](https://github.com/agentkitai/lore/blob/main/README.md)

## 1. 服务等级目标（SLO）与告警

SLO 模块把"记忆系统的可用性"提升为一等公民。CLI 提供 `lore slo` 子命令组（[src/lore/cli/commands/misc.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/misc.py) 在 `__init__.py` 的导入列表中通过 `cmd_slo` 注册，并由 `__init__.py` 的 `group_handlers` 分发路由），常见操作包括：

| 操作 | 用途 |
|------|------|
| `lore slo create` | 基于指标（`p99_latency` 等）、阈值与比较运算符定义目标 |
| `lore slo status` | 查看当前 SLO 燃烧率与达标情况 |
| `lore slo alerts` | 列出正在触发或最近触发的告警 |

SLO 指标与 `lore recall` 的延迟目标直接对应——例如 `recall()` 100 条记忆 < 50 ms、10K 条 < 200 ms、图增强检索 < 500 ms（资料来源：[README.md](https://github.com/agentkitai/lore/blob/main/README.md)），便于把性能预算固化为可执行规则。

## 2. 检索档案与生命周期策略

**检索档案（Retrieval Profiles）**允许在不同工作负载下切换排序权重，例如 `lore profiles create --name fast-coding --semantic-weight 1.0 --recency-bias 7`（资料来源：[README.md](https://github.com/agentkitai/lore/blob/main/README.md)）。CLI 子命令 `lore profiles list/create` 由 `cmd_profiles` 暴露，注册位置见 [src/lore/cli/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/__init__.py)。

**保留策略（Retention Policies）**则面向数据生命周期：

- `lore policy create --name prod --snapshot-schedule "0 2 * * *" --max-snapshots 30` 声明 cron 风格的快照计划；
- `lore policy compliance` 输出跨策略的合规仪表板；
- `lore restore-drill --latest` 触发一次带耗时指标的恢复演练。

**共享与社区能力**补充在 [src/lore/server/routes/sharing.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/sharing.py) 中：路由前缀 `/v1/sharing` 提供启用开关、人审、速率限制（默认 100/小时）、体量告警阈值（默认 1000）等配置模型 `SharingConfig` / `SharingConfigUpdate`，并通过 `AgentSharingConfig` 控制按 Agent 的类别授权。

## 3. 多租户工作空间与审计

工作空间是企业隔离的最小单元：

```mermaid
graph LR
  WS[Workspace<br/>dev-team] --> K1[API Key<br/>scoped to WS]
  WS --> K2[API Key<br/>is_root=true]
  WS --> MEM[(Memories<br/>project=WS)]
  K1 --> AUD[Audit Log<br/>memory.create / key.revoke ...]
  K2 --> AUD
```

- `lore workspace create dev-team` 与 `lore workspace switch dev-team` 切换隔离上下文；
- API Key 由 [src/lore/cli/commands/keys.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/keys.py) 的 `cmd_keys_create / list / revoke` 管理；可通过 `--root` 提升为根密钥（业务模型字段 `is_root`，见 `cmd_keys_create`）；
- `lore audit --since 24h` 通过 `cmd_audit`（注册于 [src/lore/cli/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/__init__.py) 的 `group_handlers["audit"]`）输出全部动作流水。

共享层在租户内还细粒度支持拒绝名单 `DenyListRuleData` 与审计事件 `AuditEventData`（[src/lore/server/routes/sharing.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/sharing.py)）。

## 4. 插件 SDK、推荐与分析

**插件扩展点**通过 Python `entry_points` 发现，五个生命周期钩子 `on_remember / on_recall / on_enrich / on_extract / on_score` 由 `cmd_plugin` 暴露的脚手架、热重载与测试工具支撑：`lore plugin create my-tagger`、`lore plugin list`、`lore plugin reload my-tagger`（资料来源：[README.md](https://github.com/agentkitai/lore/blob/main/README.md)，CLI 注册于 [src/lore/cli/__init__.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/__init__.py)）。

**主动推荐** `lore suggest --context "..."`（HTTP 对应 `GET /v1/recommendations`）使用上下文相似度、实体重合、时间模式与访问模式四种信号做综合打分并附人类可读解释。

**检索分析**通过 `GET /v1/analytics/retrieval` 与 Prometheus 指标暴露命中率、得分分布、记忆利用率与延迟，方便接入既有可观测栈。

## 5. 配置矩阵与排错要点

| 环境变量 | 默认 | 影响的能力 | 来源 |
|----------|------|------------|------|
| `LORE_API_URL` / `LORE_API_KEY` | — / `http://localhost:8765` | 远程服务端、CLI 与密钥命令 | [src/lore/cli/_helpers.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/_helpers.py) |
| `LORE_PROJECT` | — | 实例默认项目作用域 | [README.md](https://github.com/agentkitai/lore/blob/main/README.md) |
| `LORE_SNAPSHOT_THRESHOLD` | `30000` | 自动快照触发字符数 | [README.md](https://github.com/agentkitai/lore/blob/main/README.md) |
| `LORE_ENRICHMENT_ENABLED` / `LORE_ENRICHMENT_MODEL` | `false` / `gpt-4o-mini` | 富化管线（与图谱提取分离） | [README.md](https://github.com/agentkitai/lore/blob/main/README.md) |
| `LORE_GRAPH_*`（`DEPTH`、`CONFIDENCE_THRESHOLD`、`EXTRACTION_ENABLED`、`EXTRACTION_CONCURRENCY`、`EXTRACTION_TIMEOUT`） | `2` / `0.5` / auto / `2` / `30` | 知识图谱与 `claude` 子进程 | [README.md](https://github.com/agentkitai/lore/blob/main/README.md) |

常见失败模式：

- **图谱未启用**：`cmd_topics` 在 `_knowledge_graph_enabled=False` 时直接打印提示并 `return`（[src/lore/cli/commands/graph.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/commands/graph.py)），需先 `lore config set knowledge_graph true`；
- **远程命令缺少凭证**：`_get_api_config` 在缺失 `--api-url` / `--api-key` 或对应环境变量时打印 `Error` 并 `sys.exit(1)`（[src/lore/cli/_helpers.py](https://github.com/agentkitai/lore/blob/main/src/lore/cli/_helpers.py)）；
- **图谱提取失败**：`EXTRACTION_ENABLED=auto` 仅在本地 `claude` CLI 在 `PATH` 上时启用，不会回退到 `OPENAI_API_KEY`。

## 6. 跨语言客户端

TypeScript SDK 与 Python SDK 同源发布：`ts/package.json` 中 `name=lore-sdk`、`version=1.1.1`，构建使用 `tsup` 生成 ESM + 类型声明（资料来源：[ts/package.json](https://github.com/agentkitai/lore/blob/main/ts/package.json)），公开 `lore.remember / recall / asPrompt / get / listMemories / forget` 等接口并支持 `secret` 阻止与 PII 自动遮罩（[ts/README.md](https://github.com/agentkitai/lore/blob/main/ts/README.md)），使企业部署中前后端与脚本侧可使用同一份语义。

---

### 参见

- 主题与图谱检索：[src/lore/server/routes/topics.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/topics.py)
- 共享与社区治理：[src/lore/server/routes/sharing.py](https://github.com/agentkitai/lore/blob/main/src/lore/server/routes/sharing.py)
- v0.7.0 Living Archive 发布说明（On This Day / Verbatim Recall / Temporal Filters）：<https://github.com/agentkitai/lore/releases/tag/v0.7.0>

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：agentkitai/lore

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/agentkitai/lore | host_targets=mcp_host, openclaw, claude_code, claude, cursor

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/agentkitai/lore | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/agentkitai/lore | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/agentkitai/lore | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/agentkitai/lore | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/agentkitai/lore | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/agentkitai/lore | release_recency=unknown

<!-- canonical_name: agentkitai/lore; human_manual_source: deepwiki_human_wiki -->