ChatPulse

Important

2026-04-12 中文版补充更新说明

• 输入前链新增并稳定了“切题判断”层，当前私聊主链路为 摘要 -> 切题 -> 路由 -> 主题 -> 决策 -> 改写 -> 召回 -> 输出。
• 前端 RAG 流程条与设置面板已同步显示切题判断结果，现在可以直接看到上一轮是“切题 / 继续当前话题 / 历史追问”。
• 日期回顾链路继续加强：支持按日期浏览、分块摘要、上下文分区，并修复了强热点话题污染日期回顾的问题。
• 输入前链与路由层的输出上限整体放宽到更安全的范围，专门缓解上游中转在短结构化步骤里偷偷消耗大量 reasoning token、导致结果被截断的问题。
• 输入前链请求增加了节流和按中转限速自适应的排队，尽量减少 429 和连续 planner 报错。
• 商业街自动行动如果遇到 API 失败，现在会直接取消本轮行动并写入折叠错误日志，不再强制把角色随机丢到别的地点。
• 商业街主动私聊提示词改成“事件驱动主动”，保留主动性，但不再默认用“你在干嘛 / 你在哪 / 在吗”这类空泛开头。
• 时间行为约束进一步加强：白天语境优先级高于话题惯性，减少角色在白天还顺着旧话题继续催用户睡觉的情况。
• 当前 README 关于实时记忆架构的说明保持为现行实现：Qdrant + SQLite 正文/元数据，不再把旧的 vectra 路径写成主链路。

Important

2026-04-06 中文版更新说明

• 黑客据点现在会抓取用户过去 5 小时内与其他角色的真实私聊记录，按最近对话对象分配最多 20 条情报，并把这些对话作为“花钱买来的监听反馈”临时注入角色上下文；角色会按正常私聊/RAG链路自己做出带情绪的回应，而不是输出硬编码汇报。
• 后端重后台任务改成统一走后台队列，并加了全局并发上限，解决了之前多计时器叠在一起把前台请求拖成“空壳”的问题。
• 商业街分钟巡逻、角色自主行动、社交碰撞、私聊主动消息、群聊主动消息都已经按层恢复，并在恢复过程中做了稳定性回归。
• 大设置里新增了“后台任务队列”面板，现在可以看到真实队列状态、最近 24 小时任务历史，并按角色、群聊或商业街系统折叠显示。
• 商业街截断日志处理已经补上：疑似被截断的商业街活动会对角色隐藏，对用户显示为低存在感的折叠提示。
• 医院恢复逻辑改成住院期间每 5 分钟结算一次，不再是原来一次性瞬间恢复。
• 私聊到商业街的路由提示词进一步收紧：地点、去向、吃什么、送礼/收礼、现实状态来源这类问题会更偏向查询商业街。
• “上一轮是否路由到商业街内容”这行统计已经修正，现在会正确识别 city_detail，不再出现实际走了商业街但面板还显示“否”的情况。
• 修了一批前端问题，包括登录和重置本地界面状态卡住、127.0.0.1:5173 与 127.0.0.1:8000 地址不一致、联系人列表排版和后台任务面板可读性问题。

Important

2026-04-05 最新修复说明

• 修掉了私聊里 RAG retrieve 阶段会卡死的问题，根因是聊天链里不该现场自愈重建索引。
• 实时聊天链默认不再让本地 vectra 参与自动回退，当前主路径是 Qdrant + SQLite 正文 + lexical/semantic fallback。
• 保留了检索前的查询扩展设计，只修掉了会把实时链路拖死的部分。
• 放松了 profile 槽过滤，轻度关系化的用户画像记忆不再被白白筛掉。
• 连续相同的 API 报错现在会在私聊里合并显示，不再一条一条刷屏。
• 商业街管理员赠送物品/钱/体力现在会按正常私聊链触发角色反馈并进入后续上下文。

详细说明见下方中文的“2026-04-05 修复记录”和英文的 “2026-04-05 Fix Notes”。

简体中文 | English

简体中文

ChatPulse 是一个本地优先的 AI 社交模拟应用，前端使用 React，后端使用 Express，主存储为 SQLite，并支持接入 Qdrant 做向量记忆检索。

缓存、RAG 与向量记忆科普

如果你是第一次接触这些词，可以先把它们理解成四个分工不同的层：

• 缓存：把已经整理好的上下文、摘要或模型结果先存起来，避免每一轮都从零重算。
• SQLite：负责保存完整消息、记忆正文和业务元数据，像项目里的“资料库”。
• Qdrant：负责按语义相近去找相关记忆，像项目里的“智能检索柜”。
• RAG：不是让模型硬猜，而是先把相关历史资料找回来，再基于这些资料回答。

一句话概括就是：缓存让它更快，SQLite 负责存原文，Qdrant 负责按语义把过去找回来，RAG 负责先查再答。

技术栈

• 前端：React 19 + Vite
• 后端：Node.js + Express + ws
• 主存储：SQLite（better-sqlite3）
• 向量检索：Qdrant
• 实时记忆主路径：Qdrant + SQLite 正文/元数据

本地部署

环境要求：

• Node.js 18+
• npm 9+
• 可选：Docker Desktop（如果你想本地跑 Qdrant）

克隆仓库：

git clone https://github.com/NANA3333333/ChatPluse.git
cd ChatPulse

初始化：

npm run setup

Windows 一键安装并启动：

install-and-start.cmd

macOS / Linux 一键安装并启动：

chmod +x install-and-start.sh
./install-and-start.sh

npm run setup 会自动：

• 安装根目录、server、client 依赖
• 创建本地运行目录
• 自动生成 server/.env（如果不存在）
• 创建运行所需但不会提交到 Git 的目录

启动：

npm run dev

Windows 辅助脚本：

install-and-start.cmd
start-stack.cmd
status-stack.cmd
stop-stack.cmd

macOS / Linux 辅助脚本：

chmod +x install-and-start.sh
./install-and-start.sh

启动后访问：

• 前端：http://127.0.0.1:5173
• 后端：http://localhost:8000

首次登录：

• 用户名：Nana
• 默认密码：12345

如果你在 server/.env 中设置了 ADMIN_PASSWORD，那么全新初始化时会使用你设置的密码。

数据库、缓存与向量库初始化

首次启动时会自动创建：

• data/master.db：认证库
• data/chatpulse_user_<id>.db：每个用户自己的业务数据库
• server/public/uploads/：上传目录
• JWT secret 文件（如果环境变量未提供）

Qdrant 行为：

• Qdrant 可用时，实时记忆检索优先使用 Qdrant
• Qdrant collection 会在首次写入记忆时自动创建
• SQLite 持续保存完整消息、记忆正文和元数据

当前 README 描述的现行实时链路以 Qdrant + SQLite 正文/元数据 为主。

可选启动 Qdrant：

docker compose up -d

将已有记忆迁移到 Qdrant：

npm run migrate:qdrant

常用参数：

npm run migrate:qdrant -- --dry-run
npm run migrate:qdrant -- --user <userId>
npm run migrate:qdrant -- --character <characterId>

健康检查：

npm run doctor

常用命令：

npm run setup
npm run dev
npm run doctor
npm run migrate:qdrant
npm run cleanup:city-memories

项目结构：

client/
  src/

server/
  index.js
  db.js
  memory.js
  qdrant.js
  plugins/

scripts/
  setup-local.js
  doctor.js
  dev.js
  migrate-memories-to-qdrant.js

许可证

本项目采用 CC BY-NC-ND 4.0 许可。

这意味着：

• 允许转载和分享
• 必须注明作者 NANA3333333 / Nana 以及原始仓库链接
• 禁止商用
• 禁止修改后再发布

完整许可说明见 LICENSE 和 Creative Commons 官方页面。

---

English

ChatPulse is a local-first AI social simulation app built with React, Express, SQLite, WebSocket realtime updates, and optional Qdrant-backed memory retrieval.

2026-04-12 Update Notes

This update focused on topic switching, date recall stability, and cleaning up stale architecture notes:

• Added a dedicated topic-switch gate before the existing RAG route stage. The live pipeline is now Summary -> Switch -> Route -> Topics -> Decision -> Rewrite -> Retrieve -> Output.
• Synced the front-end RAG progress header and settings drawer so the last round can explicitly show Switch topic, Continue current topic, or History follow-up.
• Hardened the date-recall path with date-browse routing, chunked day summaries, context partitioning, and better cache invalidation for polluted strong-topic lines.
• Prevented malformed / truncated outputs from pre-planner stages (topic switch, topics, decision, and temporal browse summarize) from being reused from cache.
• Changed the topic-switch gate to fail closed: if that layer breaks, the turn now stops immediately and returns an error instead of silently falling back to continue current topic.
• Raised output-token budgets across the pre-input planner chain and router layers to reduce false truncation on upstream relays that burn excessive reasoning tokens.
• Added request pacing for pre-input planner calls so relay services with strict per-minute limits are less likely to trip repeated 429 failures.
• Changed city autonomous-action API failures to stop the action and emit a folded error record instead of randomly forcing the character to wander somewhere unrelated.
• Reworked proactive city-to-private-chat prompts so “initiative” favors event-driven updates, current state, and concrete incidents rather than repetitive openers like “what are you doing?”.
• Strengthened time-of-day guidance so daytime replies are less likely to inherit late-night inertia such as repeatedly urging the user to sleep.
• Updated this README to remove stale wording that still described vectra as part of the current real-time retrieval architecture.

Stack

• Frontend: React 19 + Vite
• Backend: Node.js + Express + ws
• Primary storage: SQLite via better-sqlite3
• Vector search: Qdrant
• Real-time memory path: Qdrant + SQLite text/metadata

Local Setup

Requirements:

• Node.js 18+
• npm 9+
• Optional: Docker Desktop if you want to run Qdrant locally

Clone:

git clone https://github.com/NANA3333333/ChatPluse.git
cd ChatPulse

Bootstrap:

npm run setup

One-click install and start on Windows:

install-and-start.cmd

One-click install and start on macOS / Linux:

chmod +x install-and-start.sh
./install-and-start.sh

npm run setup will:

• install root, server, and client dependencies
• create local runtime directories
• generate server/.env if it does not exist
• prepare runtime-only folders that are intentionally excluded from Git

Start the app:

npm run dev

Windows helper scripts:

install-and-start.cmd
start-stack.cmd
status-stack.cmd
stop-stack.cmd

macOS / Linux helper script:

chmod +x install-and-start.sh
./install-and-start.sh

URLs:

• Frontend: http://127.0.0.1:5173
• Backend: http://localhost:8000

First login:

• Username: Nana
• Default password: 12345

If you set ADMIN_PASSWORD in server/.env, that value will be used for first-run seeding on a brand-new auth database.

Databases, Cache, and Vector Initialization

On first startup, the project automatically creates:

• data/master.db for auth
• data/chatpulse_user_<id>.db per user
• server/public/uploads/
• a JWT secret file when not provided by env

Qdrant behavior:

• Uses Qdrant when reachable
• Creates Qdrant collections lazily on first memory write

SQLite stores full message / memory content and metadata. Qdrant is the active real-time vector retrieval backend.

2026-04-05 Fix Notes

Today’s work focused on the Claude private-chat path, the RAG retrieval pipeline, and a few front-end UX regressions:

• Removed chat-time self-healing index rebuilds from the live retrieval path. Previously, a normal private-chat request could enter retrieve, decide the index looked unhealthy, and start rebuilding during the reply, which caused long hangs and heavy local CPU usage.
• Disabled vectra in the real-time retrieval path by default. The current live path is effectively Qdrant + SQLite memory content + lexical/semantic fallback. Local vectra is now opt-in only via LOCAL_VECTOR_INDEX_ENABLED=1.
• Kept the retrieval-query expansion step as part of the design, but removed the parts of the live path that were causing retrieval to stall.
• Added finer-grained retrieval tracing so logs now show retrieve start/end, per-slot progress, Qdrant query phases, and fallback phases. This makes it much easier to tell whether a request is stuck in topics, rewrite, retrieve, or main output.
• Added GET /api/system/embedding-status to inspect the local bge-m3 embedding runtime: loaded state, active jobs, recent latency, and errors.
• Relaxed profile-slot filtering so lightly relationship-tinted user-profile memories can still be injected. This fixes a case where valid profile memories were being retrieved and then discarded because they mentioned possessiveness, teasing style, or interaction habits.
• City-manager gifting / money / stamina actions now go through the normal private-chat chain and can generate ordinary in-character feedback that becomes part of later conversation context.
• Expanded the private/group emoji picker, fixed the temporary ?? encoding regression, and kept the wider popup layout.
• Consecutive identical system API errors in private chat are now collapsed into a single visible message with a repeat count, instead of spamming multiple identical red bubbles.

Notes:

• Recent Claude 503 model_not_found / no available channel failures look like upstream relay/channel issues, not local RAG hangs.
• SQLite stores memory content, while Qdrant stores vector indices. The main issue uncovered today was not lost memory text; it was an unstable “index state check + self-heal during live chat” design.

Optional Qdrant startup:

docker compose up -d

Migrate existing memories into Qdrant:

npm run migrate:qdrant

Common options:

npm run migrate:qdrant -- --dry-run
npm run migrate:qdrant -- --user <userId>
npm run migrate:qdrant -- --character <characterId>

Health check:

npm run doctor

Useful commands:

npm run setup
npm run dev
npm run doctor
npm run migrate:qdrant
npm run cleanup:city-memories

License

This project is licensed under CC BY-NC-ND 4.0.

That means:

• sharing and redistribution are allowed
• attribution to NANA3333333 / Nana and the original repository is required
• commercial use is not allowed
• modified redistribution is not allowed

See LICENSE and the official Creative Commons page for details.