项目定位与核心能力

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。

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 层 → 持久化与知识图谱层。下图为各层及关键模块的依赖关系。

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 是命令注册表，按职责拆分为多个子模块：

资料来源：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

概述

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

下表概括 v0.7.0 引入的核心能力（资料来源：README.md）：

记忆操作（Memory Operations）

CLI 层

CLI 是最常用的入口，定义在 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）提供 observations list|show <id> 子命令，用于查看 capture 子代理产生的结构化观察，其输出 JSON 含 narrative、facts、tags、captured_by 等字段。
• cmd_on_this_day 定义在 src/lore/cli/commands/misc.py，调用 lore.on_this_day() 拉取与今天日期匹配的历史记忆。

CLI 通过 lore.cli._helpers._get_lore()（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 中实现了 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 中通过 SharingConfig、AgentSharingConfig 模型提供。

知识图谱（Knowledge Graph）

Lore 的知识图谱由"实体抽取 → 关系构建 → 图谱遍历"三步组成，相关 CLI 命令集中在 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）。

Cloud Server 端的话题接口在 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）。

v0.7.0 Living Archive 时间特性

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

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）。
• 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）会直接 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 — 项目总览与环境变量
• ts/README.md — TypeScript SDK 文档
• v0.7.0 发布说明：<https://github.com/agentkitai/lore/releases/tag/v0.7.0>

概述

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），这些功能同样需要借助下述集成与部署管道才能在生产环境中被多个代理同时访问。资料来源：README.md。

多代理集成模式

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

# 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 SDK 用法（ts/README.md）
import Lore from "lore-sdk";
const lore = new Lore({ /* ... */ });
await lore.remember({ content: "...", type: "lesson" });

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

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 命令包括：

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。

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 组合：

# 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 服务：

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

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

pip install lore-sdk[server]

常用环境变量整理如下：

资料来源：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
• src/lore/cli/__init__.py
• v0.7.0 Living Archive Release Notes

资料来源：README.md

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

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

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

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

检索档案（Retrieval Profiles）允许在不同工作负载下切换排序权重，例如 lore profiles create --name fast-coding --semantic-weight 1.0 --recency-bias 7（资料来源：README.md）。CLI 子命令 lore profiles list/create 由 cmd_profiles 暴露，注册位置见 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 中：路由前缀 /v1/sharing 提供启用开关、人审、速率限制（默认 100/小时）、体量告警阈值（默认 1000）等配置模型 SharingConfig / SharingConfigUpdate，并通过 AgentSharingConfig 控制按 Agent 的类别授权。

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

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

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 的 cmd_keys_create / list / revoke 管理；可通过 --root 提升为根密钥（业务模型字段 is_root，见 cmd_keys_create）；
• lore audit --since 24h 通过 cmd_audit（注册于 src/lore/cli/__init__.py 的 group_handlers["audit"]）输出全部动作流水。

共享层在租户内还细粒度支持拒绝名单 DenyListRuleData 与审计事件 AuditEventData（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，CLI 注册于 src/lore/cli/__init__.py）。

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

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

5. 配置矩阵与排错要点

常见失败模式：

• 图谱未启用：cmd_topics 在 _knowledge_graph_enabled=False 时直接打印提示并 return（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）；
• 图谱提取失败：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），公开 lore.remember / recall / asPrompt / get / listMemories / forget 等接口并支持 secret 阻止与 PII 自动遮罩（ts/README.md），使企业部署中前后端与脚本侧可使用同一份语义。

Pitfall Log / 踩坑日志

项目：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