基于 Hindsight 记忆系统构建候选人立场追踪器Stance Tracker从架构设计到 Vercel 部署的完整实战指南【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsightStance Tracker是 Hindsight Cookbook 中一个完整、可运行的参考应用它把「网络爬取 LLM 分析 记忆系统」组合在一起实现对政治候选人立场Stance的持续追踪与时序演变分析。本文以该应用为骨架完整讲解其功能设计、内存系统集成方式、本地部署步骤、REST API 设计、Hindsight retain/recall/reflect 的实战用法并结合当前仓库源码剖析记忆写入、语义检索与时序过滤的底层实现。读完本文你将掌握如何用 Hindsight 的 Bank / Retain / Recall / Reflect 四件套搭建一个带时间维度的领域追踪型应用并具备将其扩展到任意「持续追踪某类实体观点变化」场景的能力。原文出处hindsight-docs/src/pages/cookbook/applications/stancetracker.md。应用概览这是一个什么样的应用Stance Tracker 是一个由 AI 驱动、基于 Hindsight 记忆系统与网页抓取技术构建的应用用于随时间追踪政治候选人在各个议题上的立场。它解决的核心问题是候选人公开表态分散在海量网页中且立场会随时间演进——如何自动采集、语义记忆、按时序检索并最终回答「这位候选人在这个议题上立场如何、何时发生了变化」。应用的核心能力包括地理定向Geographic Targeting按国家、州/省、城市三级粒度追踪立场同一候选人可针对不同地区分别分析多候选人追踪Multi-Candidate Tracking同时监控多位候选人互不干扰时间维度分析Temporal Analysis历史立场追踪支持可配置的时间范围回答「过去三个月这位候选人的态度变化」这类问题自动化采集Automated Scraping周期性内容收集频率可按小时 / 天 / 周配置立场变化检测Stance Change Detection自动检测并高亮立场发生变化的节点交互式时间线Interactive Timeline用可视化图表展示立场演化并带有引用标注reference callouts来源归因Source Attribution每条立场都关联到经过验证的来源与原文摘录。架构设计Hindsight 记忆系统如何被接入记忆系统Hindsight IntegrationStance Tracker 使用 Hindsight 记忆系统作为「立场事实库」其内存模型由四个核心操作组成对应本文仓库中 hindsight-api-slim 的核心引擎Banks记忆库每个爬取 Agent 拥有独立的记忆银行。银行是 Hindsight 中记忆与身份的基本隔离单元支持设置mission使命陈述与disposition人格倾向对应客户端封装 client_wrapper.py 中的BanksAPI.create / set_mission / set_dispositionRetain写入存储候选人陈述与网页抓取结果写入时自动完成分块、实体解析与索引Recall检索语义搜索按相关性取回与问题相关的记忆片段Reflect反思基于已存记忆生成上下文相关的分析回答输出「这位候选人在 X 议题上的立场是……」这类结论Temporal Search时序检索在特定时间点或时间段内查询记忆支撑「截止到 2024-12-01 的立场」这类查询。技术栈层选型前端Next.js 16、React、TypeScript、TailwindCSS可视化Recharts时间线图后端Next.js API Routes记忆Hindsight内存系统数据库JSON 文件存储无需数据库网络搜索Tavily APILLMOpenAI / Anthropic / Groq可配置调度node-cron端到端数据流一次典型的「立场更新」流程为node-cron 调度器触发 →scraper-agent通过web-scraperTavily采集候选人与议题相关的网页 →stance-extractor调用 LLM 提取立场表述 → 通过hindsight-client将结果retain进该候选人的银行 → 用户在时间线上发起recall或reflect查询 → 前端以 Recharts 时间线展示。环境准备Prerequisites开始前需要准备两样东西一个正在运行的 Hindsight API 服务Stance Tracker 通过 HTTP 与 Hindsight 通信默认http://localhost:8888两组 API KeyTavily API Key用于网络搜索LLM 服务商 API KeyOpenAI、Anthropic 或 Groq 三选一。从当前仓库看Hindsight 服务端本体位于 hindsight-api-slimPython 实现其入口为 hindsight-api-slim/hindsight_api/main.py官方客户端库在 hindsight-clients/python/hindsight_client/hindsight_client.pyStance Tracker 的lib/hindsight-client.ts正是这套 API 的 TypeScript 等价封装。本地部署四步跑通1. 安装依赖npm install2. 配置环境变量复制.env.example为.env并填入凭据cp .env.example .env编辑.env# Hindsight API记忆服务地址 HINDSIGHT_API_URLhttp://localhost:8888 # Tavily API用于网络搜索 TAVILY_API_KEYyour_tavily_api_key_here # LLM Provider LLM_PROVIDERopenai # 或 anthropic、groq LLM_API_KEYyour_llm_api_key_here LLM_MODELgpt-4-turbo-preview3. 启动 Hindsight 服务克隆并运行 Hindsight即当前仓库所对应的github.com/vectorize-io/hindsightcd /path/to/hindsight cargo run --bin hindsight-server启动后访问http://localhost:8888验证服务是否就绪。提示HINDSIGHT_API_URL指向的是 Hindsight 记忆服务的 HTTP 端点Stance Tracker 所有 retain/recall/reflect 调用都会打到该地址。若你使用当前仓库的 Python 实现可参考 hindsight-api-slim/README.md 完成服务端启动该服务端在 http.py 中实现了retain_memories / recall_memories / reflect等 REST 端点。4. 启动应用npm run dev访问http://localhost:3000即进入主界面。使用指南创建会话、查看结果与管理会话创建追踪会话Creating a Tracking Session在界面上按以下步骤完成一次追踪配置设置地点Set Location国家为必填州/省与城市可选决定爬取与分析的地区范围选择议题Choose Topic指定要追踪的议题例如 Climate Change Policy添加候选人Add Candidates输入要追踪的候选人/政治家姓名配置时间范围Configure Time Range设置历史分析的起止日期用于初始化回溯分析设置频率Set Frequency选择更新检查频率hourly每小时/ daily每天/ weekly每周开始追踪Start Tracking点击按钮调度器接管后续周期性采集。查看结果Viewing Results时间线图Timeline Graph展示每位候选人立场置信度随时间的变化曲线立场变化Stance Changes图上红色圆点标识检测到的立场转变节点点击数据点Click Points点击任意数据点查看详细的立场信息与来源来源链接Source Links每条立场均包含指向原始参考资料的链接。管理会话Managing SessionsPause / Resume临时暂停或恢复追踪Run Now在既定计划之外立即触发一次更新Status查看当前会话状态与更新频率。REST API 端点设计Stance Tracker 将「会话管理」「立场数据」「调度控制」拆分为三组 API会话SessionsPOST /api/sessions— 创建新的追踪会话GET /api/sessions?id{id}— 获取会话详情GET /api/sessions— 列出所有会话PATCH /api/sessions— 更新会话状态立场StancesPOST /api/stances— 处理候选人立场数据GET /api/stances?sessionId{id}candidate{name}— 获取指定会话与候选人的立场列表调度器SchedulerPOST /api/scheduler— 控制会话调度支持start、stop、run三种动作这一设计把「数据接入」POST stances与「查询展示」GET stances分离会话状态机则由 scheduler 统一驱动方便前端在 Pause/Resume/Run Now 之间切换。Hindsight 集成实战四个核心调用及其源码原理这是整个应用最值得深入的部分。以下代码来自原文档我们将逐个对照当前仓库的 Python 服务端与客户端实现说明每个调用背后的真实行为。1. 存储记忆Retain// 存储网页抓取结果 await hindsightClient.retain(bankId, articleContent, { context: web_search_result, timestamp: articleDate, metadata: { url: articleUrl } });服务端对应实现位于 memory_engine.py 的retain_async它接受bank_id、content文本内容、context记忆形成时的上下文、event_date事件发生时间缺省为当前时间与document_id。从实现可以看到retain_async最终委托给retain_batch_async将内容封装为{content: ..., context: ..., event_date: ...}后批量写入——这意味着event_date / timestamp 会作为记忆的时间戳写入成为后续时序检索的基础。写入过程还会自动完成实体解析与索引构建这正是 Stance Tracker 能按「候选人实体」聚合立场的原因。2. 语义搜索Recall// 搜索相关记忆 const results await hindsightClient.recall(bankId, query, { budget: high, maxTokens: 8192 });Recall 是 Hindsight 检索能力的核心。服务端recall_asyncmemory_engine.py实现了N×4 路并行检索对每种事实类型fact type如world/experience/observation并行执行 4 种检索语义向量semantic vector、BM25 关键词keyword、图激活graph activation、时序图temporal graph使用Reciprocal Rank FusionRRF融合各路结果用所选重排器启发式或 cross-encoder重排打分应用MMR去重以保持多样性按max_tokens预算截断输出。参数方面budget控制图遍历深度low100、mid300、high600单位maxTokens控制返回结果的最大 token 数服务端默认 4096。客户端签名见 hindsight_client.py除budget / max_tokens外还支持types、tags、tags_match、min_scores、include_entities等丰富过滤项。此外银行级开关enable_text_search、enable_temporal_retrieval、enable_graph_retrieval可独立关闭某一检索臂见 memory_engine.py从而以召回广度换延迟。3. 时序过滤Temporal Filtering// 查询截至某个时间点的记忆 const results await hindsightClient.recall(bankId, query, { queryTimestamp: 2024-12-01T00:00:00Z });时序能力在服务端对应recall_async的question_date参数memory_engine.py 及 interface.py它同时作用于相对时间表达式的解析如「上个月」与新近度打分recency scoring——即回答问题时以该时间点为锚而不是「现在」。REST 层对应query_timestamp请求参数服务端在 http.py 中将其解析为 ISO 格式的question_date传入引擎。这正是 Stance Tracker 实现「时间线回放」的关键给定某个历史时刻可以还原出「彼时彼刻」的立场状态。仓库中 test_recall_temporal_window.py 与 test_recall_time_range.py 等测试覆盖了这类时序检索行为。4. 上下文分析Reflect// 基于已存记忆生成分析 const response await hindsightClient.reflect(bankId, What is the candidate\s stance on this issue?, { budget: high } );Reflect 在服务端对应reflect端点与 think_utils.py 中独立实现的reflect函数它会将银行中的experience_facts经验事实与world_facts世界事实格式化后组装进「思考提示词」并注入银行的disposition人格特质如 skepticism/literalism/empathy与background然后调用 LLM 生成第一人称、基于事实的回答——不会编造提示词之外的信息。对 Stance Tracker 而言reflect就是把候选人在银行中的零散表态综合成一个立场判断的高级入口。客户端封装见 hindsight_client.py支持context、response_schema结构化输出、tags过滤等。生产部署Vercel 方案与注意事项# 安装 Vercel CLI npm i -g vercel # 部署 vercel # 在 Vercel 控制台配置环境变量 # - HINDSIGHT_API_URL # - TAVILY_API_KEY # - LLM_PROVIDER # - LLM_API_KEY # - LLM_MODEL重要提醒Stance Tracker 的data/目录使用 JSON 文件存储在 Vercel 上属于临时文件系统重启即丢失。生产环境应改用持久化数据库或对象存储——Hindsight 服务端本身支持 Postgres 等多种存储后端可将记忆层托管到持久化实例而将应用自身的会话元数据迁移到托管数据库。项目结构解析与二次开发项目结构stancetracker/ ├── app/ │ ├── api/ # API 路由 │ ├── globals.css # 全局样式 │ ├── layout.tsx # 根布局 │ └── page.tsx # 主页面 ├── components/ # React 组件 ├── lib/ │ ├── db/ # JSON 数据库工具 │ ├── hindsight-client.ts # Hindsight API 客户端 │ ├── llm-client.ts # LLM 服务商客户端 │ ├── web-scraper.ts # Tavily 网页抓取器 │ ├── scraper-agent.ts # 内容抓取 Agent │ ├── rag-system.ts # 记忆检索RAG │ ├── stance-extractor.ts # 立场分析 │ ├── stance-pipeline.ts # 主流水线 │ └── scheduler.ts # 任务调度 └── types/ # TypeScript 类型定义lib/目录清晰划分了各层职责hindsight-client.ts负责与 Hindsight 通信web-scraper.tsscraper-agent.ts负责采集stance-extractor.tsstance-pipeline.ts负责从原文到立场的提炼rag-system.ts负责检索增强scheduler.ts基于 node-cron 驱动周期性任务。扩展新的 LLM 服务商编辑lib/llm-client.ts并新增一个方法即可接入新的服务商private async newProviderComplete(messages, options) { // 实现 }原文档给出的LLM_PROVIDER支持openai、anthropic、groq三档扩展时只需保持complete方法签名一致上层stance-extractor与reflect调用无需改动。局限性与演进方向已知限制网络搜索依赖 Tavily API存在速率限制rate limits来源验证关键场景建议人工复核来源真实性立场抽取基于 LLM受模型能力限制存在误判可能存储JSON 文件存储不适合大规模生产场景速率限制需尊重 Tavily、Hindsight 与 LLM 服务商各自的速率限制。未来增强路线原文档列出的演进方向包括实时社交媒体监控、演讲/视频转写分析、多语言支持、情感分析集成、对比分析面板、CSV/PDF 导出、立场变化邮件通知、面向第三方集成的公共 API。许可证Stance Tracker 采用MIT许可证可自由用于学习与二次开发。更多同类完整应用可继续阅读 hindsight-docs/src/pages/cookbook/index.mdx 中收录的其他 Cookbook 应用如 chat-memory.md它们是理解 Hindsight 在不同业务形态下如何落地的最佳范本。【免费下载链接】hindsightHindsight: Agent Memory That Learns项目地址: https://gitcode.com/GitHub_Trending/hindsight2/hindsight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考