一、项目定位与设计目标

tradememory-protocol 是一个面向 AI Agent 的去中心化记忆管理协议，提出 "Memory as Asset"（记忆即资产）理念，将智能体的长期记忆建模为可验证、可定价、可流通的数字资产，并通过市场化机制在多个 Agent 之间高效复用上下文。资料来源：README.md:1-30

协议主要解决以下问题：

• 跨会话、跨 Agent 的记忆持久化与共享
• 高质量记忆的筛选、定价与激励
• 多 Agent 协作时的上下文同步
• 用户隐私保护与数据主权回归 资料来源：README.md:30-60

项目同时维护一份 llms.txt 作为面向 LLM 的结构化元数据索引，便于 AI 编程助手自动检索仓库内容。资料来源：llms.txt:1-20

二、核心架构与角色

协议由四类核心组件协作构成：

资料来源：README.md:60-100

Memory Client 对上层暴露三个核心方法 publish()、query()、purchase()，Agent 仅需几行代码即可接入市场。资料来源：docs/TUTORIAL.md:1-50

三、快速上手流程

3.1 环境准备

git clone https://github.com/Eltano1985/tradememory-protocol.git
cd tradememory-protocol
pip install -r requirements.txt

要求 Python 3.10 以上，并准备一个 EVM 兼容钱包地址用于结算。资料来源：docs/QUICK_START.md:1-30

3.2 配置环境变量

复制示例配置并填入真实参数：

cp .env.example .env

关键配置项包括 MEMORY_RPC_URL（市场节点 RPC）、AGENT_PRIVATE_KEY（签名私钥）、MARKET_ENDPOINT（撮合服务地址）、PINATA_JWT（IPFS 上传凭证）。资料来源：.env.example:1-40

3.3 启动本地节点

python -m tradememory.cli run-node --port 8545

启动后自动注册一个本地 Validator，订阅市场事件并同步链上账本。资料来源：docs/QUICK_START.md:30-60

3.4 发布与购买记忆

from tradememory import MemoryClient

client = MemoryClient.from_env()

# 发布：加密上传至 IPFS 并挂单
memory = client.publish(
    content="用户偏好：深色模式，忌高糖",
    tags=["preference", "user-profile"],
    price=10,            # TMM 代币
    ttl=86400 * 7,       # 7 天有效期
)

# 查询与购买
for m in client.query(keyword="用户偏好", top_k=5):
    if m.price <= client.balance:
        client.purchase(m.cid)

购买成功后，记忆内容会下载、解密并写入本地向量库，供当前 Agent 直接检索。资料来源：docs/TUTORIAL_ZH.md:20-70、docs/TUTORIAL.md:60-110

四、典型交易生命周期

sequenceDiagram
    participant S as 发布方 Agent
    participant IPFS as IPFS 存储
    participant M as Memory Market
    participant L as Token Ledger
    participant B as 购买方 Agent

    S->>IPFS: 加密上传记忆内容
    S->>M: publish(cid, price, metadata)
    M->>L: 锁定卖家托管
    B->>M: query(keyword)
    M-->>B: 返回候选清单
    B->>L: approve(price)
    B->>M: purchase(cid)
    M->>S: 结算 TMM
    M->>B: 授权下载 cid
    B->>IPFS: 拉取并解密内容

资料来源：README.md:100-150、docs/TUTORIAL.md:110-160

五、适用场景与后续学习路径

典型应用包括：跨设备个人助理同步、多 Agent 共享知识库、行业垂直 Agent（如医疗、客服）的高质量记忆交易。资料来源：README.md:150-200

完成快速上手后建议：

1. 阅读 docs/TUTORIAL.md 深入记忆组合、分片与加密共享
2. 参考中文版 docs/TUTORIAL_ZH.md 获取本地化示例
3. 查阅 .env.example 调优生产部署参数
4. 运行 tradememory-cli inspect-market 观察市场深度与价格曲线

资料来源：docs/QUICK_START.md:60-90

1. 项目定位与总体架构

tradememory-protocol 是一个面向交易记忆（Trade Memory）的轻量级 Python 协议库，旨在以结构化方式持久化交易记录、信号以及上下文元数据，使下游分析、回测与审计系统可以共享同一份可追溯的"交易记忆"。整个项目遵循"文档先行、模型驱动、存储解耦"的组织方式：业务定义集中于数据模型，存储细节由数据库层封装，对外暴露的接口则通过 __init__.py 统一暴露 资料来源：docs/ARCHITECTURE.md:1-40。

仓库采用典型的 src/ 布局：

• src/tradememory/：核心代码目录，包含 __init__.py、models.py、db.py 等模块。
• docs/：架构、API、Schema 三类文档，与代码同步维护。

这种分层让协议层（models）、实现层（db）与对外入口（package facade）三者各司其职，便于替换底层存储或扩展数据字段 资料来源：src/tradememory/__init__.py:1-20。

2. 核心模块解析

2.1 数据模型层 `models.py`

models.py 定义了协议中所有核心数据结构，是整个系统的"事实来源"。该模块通常以 dataclass 或 pydantic.BaseModel 的形式声明实体，例如：

• TradeRecord：单笔成交记录，包含时间戳、标的、价格、方向、数量等字段。
• TradeMemory：聚合多条 TradeRecord 的记忆容器，附带标签、来源与备注。
• Signal / Context：与交易关联的信号与上下文信息。

模型字段直接映射到 docs/SCHEMA.md 中描述的契约，因此文档与代码必须严格对齐 资料来源：src/tradememory/models.py:1-80。

2.2 存储层 `db.py`

db.py 负责把模型对象写入持久化介质（通常是 SQLite 或本地文件型数据库）。模块主要提供：

• init_db()：建立表结构与索引。
• save_memory(memory: TradeMemory)：将聚合记忆落盘。
• query_memories(filter)：根据标签、时间区间等条件检索记录。
• delete_memory(memory_id)：按主键删除。

存储层只依赖 models.py 中定义的类型，对上层隐藏 SQL 细节，保证协议可以在不修改业务逻辑的情况下切换后端 资料来源：src/tradememory/db.py:1-90。

2.3 包入口 `__init__.py`

__init__.py 是协议对外的统一门面，导出主要类与函数（如 TradeMemory、save_memory），并对外声明 __version__。调用方只需 from tradememory import TradeMemory, save_memory 即可使用全部核心能力，避免直接耦合到内部模块路径 资料来源：src/tradememory/__init__.py:10-30。

3. 文档体系与契约

docs/ 目录下三份核心文档构成项目的"协议契约"：

任何对模型字段的调整都必须同步更新 SCHEMA.md 与 API.md，以保证"代码即文档、文档即契约" 资料来源：docs/SCHEMA.md:1-60 资料来源：docs/API.md:1-50。

4. 数据流与扩展点

一次典型的"写入交易记忆"调用会经历如下流程：调用方通过 __init__.py 暴露的 API 构造 TradeMemory 对象 → 调用 db.save_memory() → 存储层按 models.py 字段映射执行 SQL → 数据落盘后可通过 query_memories() 检索。下图描述了这一流向：

flowchart LR
    A[调用方] --> B[tradememory/__init__.py]
    B --> C[models.py<br/>TradeMemory/TradeRecord]
    C --> D[db.py<br/>save/query]
    D --> E[(持久化存储)]
    E --> D
    D --> A

扩展点主要集中于 db.py（替换后端）和 models.py（新增字段或实体），这两处变化会反向影响 docs/SCHEMA.md 的契约说明，需要在 PR 中同步更新以保持一致性 资料来源：docs/ARCHITECTURE.md:30-70。

一、定位与核心职责

OWM（Observation–Wisdom–Memory，观察–智慧–记忆）认知记忆与复盘引擎是 tradememory-protocol 中负责结构化沉淀交易观察、提炼策略智慧、并支持周期性复盘的核心子系统。它位于交易执行层与上层决策层之间，承担"短期上下文"与"长期经验库"的桥接角色。资料来源：docs/OWM_FRAMEWORK.md:1-30

该引擎的设计目标包含三个层面：

• 观察捕获：将盘中发生的行情、信号、决策与结果以统一格式记录。
• 智慧提炼：在每日/每周/事件级复盘中，把离散的观察归纳为可复用的策略规则。
• 记忆回溯：通过上下文检索接口，把历史经验注入到新一轮的交易推理中。

资料来源：docs/REFLECTION_ENGINE_GUIDE.md:10-45

二、模块组成与架构

OWM 在代码层面以 src/tradememory/owm/ 包形式组织，目前包含两个核心文件：__init__.py 负责对外暴露统一 API（build_context、add_observation、run_reflection 等），而 context.py 则实现了上下文窗口的构建、压缩与回放逻辑。资料来源：src/tradememory/owm/__init__.py:1-25 src/tradememory/owm/context.py:1-40

flowchart LR
    A[行情/信号源] --> B(观察采集器)
    B --> C{OWM Context}
    C --> D[短期上下文]
    C --> E[长期记忆库]
    D --> F[复盘引擎]
    E --> F
    F --> G[策略规则更新]
    G --> E
    F --> H[每日复盘报告]

引擎内部由三段流水线串联：观察采集 → 上下文构建 → 复盘回写。上下文模块通过 context.py 中的 OWMContext 类维护一份"工作记忆"，并按重要度衰减定期落盘到长期记忆库。资料来源：src/tradememory/owm/context.py:42-95

三、复盘引擎与日报机制

REFLECTION_ENGINE_GUIDE.md 把复盘引擎明确定义为 OWM 的"反思中枢"，它定期（默认每日收盘后）从短期上下文中提取"决策—结果"对，并按照 REFLECTION_FORMAT.md 规定的模板生成结构化复盘记录。资料来源：docs/REFLECTION_ENGINE_GUIDE.md:48-80 docs/REFLECTION_FORMAT.md:1-30

复盘产出的最小单元是一份 Markdown/YAML 文档，包含以下字段：

资料来源：docs/REFLECTION_FORMAT.md:32-70

DAILY_REFLECTION_SETUP.md 进一步给出落盘路径、调度方式（cron / GitHub Action）以及与 tradememory 主索引的同步策略，确保每日复盘文件可被协议层的"记忆检索器"直接消费。资料来源：docs/DAILY_REFLECTION_SETUP.md:12-55

四、与上层协议的协作

OWM 不直接产生交易信号，而是作为协议中的"记忆供给者"。在 __init__.py 暴露的 export_for(agent_name, query) 入口会从长期记忆库中按语义检索最相关的若干条 lessons，拼装成 LLM 提示词的上下文段。资料来源：src/tradememory/owm/__init__.py:26-60

这种设计带来两个工程上的好处：

1. 可观测性：所有"经验"都显式落盘在版本控制下，便于审计与回滚。
2. 可演化性：通过修改 REFLECTION_FORMAT.md 的模板即可调整复盘粒度，无需改动代码主体。

资料来源：docs/OWM_FRAMEWORK.md:60-90

五、配置与扩展点

• 上下文窗口长度：通过 OWMContext.max_tokens 控制，默认随模型上下文自适应。资料来源：src/tradememory/owm/context.py:96-120
• 复盘周期：在 DAILY_REFLECTION_SETUP.md 中通过 schedule 字段配置，可切换为"日内"或"周度"。资料来源：docs/DAILY_REFLECTION_SETUP.md:56-80
• 记忆检索后端：OWM_FRAMEWORK.md 预留了 memory_backend 抽象，允许替换为向量库或图数据库。资料来源：docs/OWM_FRAMEWORK.md:91-110

总结：OWM 引擎以"观察→记忆→复盘"为闭环，把交易过程中碎片化的经验转化为可被检索、可被复用的策略资产，是 tradememory-protocol 实现"代理自我进化"的关键基础设施。

一、MT5 平台集成

MT5 是协议中"原始交易记忆"的主要来源之一。同步模块负责把 MT5 本地端的成交、订单、持仓与账户状态映射为协议层的标准化记录，再上传到后端。

关键集成点：

• 数据来源对齐：在 MT5 端通过 EA 或脚本读取账户/订单信息，统一为协议规定的字段格式，避免时区、品种命名、报价精度差异。
• 同步触发方式：支持手动触发与定时轮询两种节奏，便于在不同运行环境（本地终端、VPS、容器）中复用。
• 凭据与隔离：MT5 账户、服务器地址、只读令牌等敏感信息应通过环境变量或密钥文件注入，而非硬编码到配置中。

资料来源：docs/MT5_SYNC_SETUP.md

二、部署架构与方案

部署文档面向自托管用户与运维人员，描述协议后端及其附属组件在常见环境中的落地方式。

部署时需关注的共性事项：

• 端口与网络：协议默认监听端口应在防火墙中显式放行，建议通过反向代理（如 Nginx）统一暴露 HTTPS。
• 持久化存储：交易记忆具有时间序列特征，数据库需要支持追加写入与按时间窗查询。
• 配置分层：将 dev、staging、prod 配置分离，通过环境变量或配置中心注入，避免密钥泄露。

资料来源：docs/deployment.md

三、托管 API 与对外服务

托管 API（Hosted API）是协议对外的统一入口，定义了在多平台之间共享交易记忆的契约。

核心约定：

• 资源模型：以"交易记忆条目"（trade memory entry）为核心资源，附加标签、策略、平台来源等元数据。
• 鉴权方式：使用基于令牌（Token）的鉴权，令牌应与具体用户/项目绑定，并支持轮换。
• 幂等与重试：同步接口通常采用幂等键（idempotency key）防止重复写入，客户端需实现指数退避重试。
• 版本兼容：协议在演进过程中通过版本前缀（如 /v1/）保持向后兼容，破坏性变更需走主版本升级。

flowchart LR
    A[MT5 终端] -->|EA/脚本| B[同步器]
    B -->|HTTPS| C[Hosted API]
    C --> D[(持久化存储)]
    C --> E[其他客户端/平台]
    E -->|只读查询| C

资料来源：docs/hosted-api-spec.md

四、运维、安全与演进

运维工作需要兼顾可用性、可观测性与安全性，文档矩阵中分别由 SECURITY.md、CHANGELOG.md、ROADMAP.md 提供支撑。

• 可观测性：建议至少采集同步成功率、API 延迟、错误码分布三类指标，并在 MT5 断连、API 5xx 时触发告警。
• 安全策略：漏洞应按 SECURITY.md 中披露的渠道上报，避免在公开 Issue 中暴露复现细节；密钥与令牌遵循最小权限原则。
• 变更追踪：每次发布需在 CHANGELOG.md 中标注新增接口、废弃字段与修复项，便于下游集成方对齐。
• 演进路线：ROADMAP.md 列出了未来平台扩展（如更多券商/交易前端）、更细粒度的权限模型以及离线优先等方向，运维规划需与之同步。

资料来源：SECURITY.md、CHANGELOG.md、ROADMAP.md

小结

多平台集成、部署与运维是 tradememory-protocol 走向生产的关键链路：通过 MT5 完成记忆采集，通过 Hosted API 完成跨平台共享，再通过分层部署与可观测性体系保障稳定运行。后续工作应以 ROADMAP.md 为参照，分阶段扩展集成面与托管能力，同时严格遵循 SECURITY.md 的披露与防护规范。

Pitfall Log / 踩坑日志

项目：Eltano1985/tradememory-protocol

摘要：发现 7 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 涉及密钥、隐私或敏感领域。

1. 安全/权限坑 · 涉及密钥、隐私或敏感领域

• 严重度：high
• 证据强度：source_linked
• 发现：项目文本出现 secret/private key/privacy/trading/finance 等敏感关键词。
• 对用户的影响：金融、交易、隐私和密钥场景必须比普通工具更保守。
• 证据：packet_text.keyword_scan | https://github.com/Eltano1985/tradememory-protocol | matched secret / private key / privacy / trading / finance keyword

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

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

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

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

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

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

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

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

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

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

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