Skip to content
项目

spearsheep/anima-brain has 53 GitHub stars and 8 forks. GitHot measured +19 stars in 24 hours. Last checked 2026-11-17 02:58 UTC. Last push 2026-11-13.

这些数字如何统计

53 星标8 复刻 +19 24小时

实测星标增长

24小时
+19
7天
正在收集历史
15天
正在收集历史
1个月
正在收集历史

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Local-first memory and emotional continuity for AI companions. Python SDK, MCP integrations, and an optional web showcase.

网站与应用

README.zh-CN.md

原文

Anima Lab

Anima Brain

English   |   简体中文

为 AI 伙伴提供长期记忆与情绪连续性。

Python 3.11+   ·   Alpha 0.6.0   ·   代码采用 MIT 许可证

快速开始   /   Python SDK   /   接入现有 Agent   /   开发文档   /   体验 Anima

做一个能聊天的角色不难,难的是让下一次聊天真正接得上:记得用户说过什么,分清哪些事情已经变了,也保留相处过程中的熟悉感。

Anima Brain 为此提供 持久记忆、角色设定和情绪连续性。你可以在 Python 里直接调用,也可以通过 MCP 接到已有 Agent,或者用自己的前端做产品。回复模型由你选择;想先看看实际效果,可以启动仓库自带的 Companion Studio 网页示例。

项目对外名称为 Anima Brain。为兼容已有接入,Python 包名仍是 companion-engine,导入使用 companion_engine,命令行入口仍是 companion。

项目源于 Anima Lab 的记忆与角色架构,并针对 Python 开发者重新组织了存储、配置和接口。这里是独立适配的开发工具,不是 Anima 线上后端的完整开源版;默认设置和能力范围也不完全相同。 具体差异见架构说明。

能给你的 Agent 加上什么

能力 具体做什么
有出处的记忆 保存原始对话、带引用的事实、纠错记录,以及帮助检索的注释和证据关联,方便回看一条记忆是怎么来的。
跨对话的连续性 本地关键词检索、可选向量检索、有限次数的补查,以及带来源的核心笔记和事件摘要。
角色与表达 配置角色性格、表达偏好,记录当前对话的情绪线索与回应意图;还可启用虚构的角色情绪和关系状态。
多模态能力 通过分别配置的服务接入看图、生成图片、参考图编辑、语音合成和转写。
实时通话 流式 Doubao 语音识别接入同一套对话与记忆流程,再用角色音色回复;可选 Vidu S2 驱动动态视频,通过托管 RTC 传输。
应用层控制 类型化返回值、记忆审核、上下文预算、用量记录,以及按请求 ID 重放结果,便于处理重试。

数据保存在本地 SQLite 中,关键词检索使用 FTS5,不依赖 Anima 账号或 Convex 后端。

Python 核心包不依赖前端。 可选的 React 展示页放在 examples/showcase/,可以聊天、编辑记忆、查看模型实际收到的上下文。支持 MCP Apps 的宿主还可以显示记忆操作卡片和语音播放控件。

快速开始

需要 Python 3.11+,以及支持 FTS5 的 SQLite。先下载仓库,再运行离线示例:

git clone https://github.com/spearsheep/anima-brain.git
cd anima-brain
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python examples/offline_demo.py

这个离线示例使用虚构数据,不会调用模型,也不需要 API key,适合先了解记忆如何保存和更新。

要开始真实对话,再配置兼容 Chat Completions、支持 JSON 对象输出的模型服务:

export COMPANION_BASE_URL='https://your-provider.example/v1'
export COMPANION_MODEL='your-model-id'
# 在 Bash 中输入密钥,避免把密钥内容写进命令历史。
read -s -p 'API key: ' COMPANION_API_KEY
export COMPANION_API_KEY
python examples/chat.py

把地址和模型名换成你的服务配置。模型调用使用你自己的账号额度,项目不会自动替你选择服务商或模型。

终端示例默认会检索记忆,但不会为了规划补查额外调用模型。更多选项见 python examples/chat.py --help,包括补查次数、历史窗口和记忆写入策略。

想先体验交互?启动网页示例

Companion Studio:角色聊天、记忆查看与编辑

Companion Studio 延续了 Anima 的纸张与墨色风格,支持角色切换、聊天、记忆审核和来源查看。它调用的就是 SDK 的实际实现,可以作为你搭建自己前端时的参考。

除上面的 Python 环境外,还需要 Node.js 22.12+ 和 npm。

python -m pip install -e '.[http,calls]'
npm ci --prefix examples/showcase
npm run build --prefix examples/showcase
python examples/showcase/serve.py --open

启动后可以在页面里配置模型。只想预览界面时,在最后一条命令末尾加 --demo,页面会明确标注这是使用预设回复的离线演示。

展示页也接入了实时语音与动态视频通话,需要另行配置对应服务和角色音色。完整说明见安装、功能与存储位置。

这是供单个用户在本机运行的示例。如果要部署给多人使用,需要自行接入身份验证、权限和部署服务。

这套“大脑”怎么工作

中文架构动图:原始对话、语义与情景记忆、巩固循环、检索公式和情绪更新

中文静态架构图 · 完整机制说明(英文)

启动展示页后,打开中文交互架构图,可以逐步播放四条流程。页面顶部可切换 English / 简体中文:

  • 记忆怎么分工:原话保留细节;语义记忆保存事实和偏好;情景记忆记录发生过的事;核心笔记把长期信息整理成紧凑的上下文。
  • 怎么把相关信息找回来:展示实际使用的 RRF 排序,以及待跟进事项如何结合重要性、情绪强度、时间衰减和日期紧迫度排序。这是两套不同的分数。
  • 历史怎么整理、旧信息怎么更新:从达到整理阈值,到写摘要、校验来源、刷新索引;事实被纠正后,受影响的摘要也需要更新。
  • 情绪怎么延续:展示角色的 PAD 状态、关系维度、衰减速度和变化限制,并可拖动参数观察结果。

上面的中文动图和静态图直接保存在仓库中,在 GitHub 上即可查看。交互页需要启动本地展示服务。图内标注、步骤说明与公式演示均提供中英文,两种语言共用流程与计算逻辑。所有示例都不会调用模型或读取你的私有聊天;交互页支持暂停、逐步查看和减少动画模式。

文字聊天与通话共用同一套记忆流程。SDK 的 brain.call(character_id, CallOptions(...)) 提供流式音频、转写、打断、静音及已保存的传递记录,详见通话接入指南。

在 Python 里接入

配置好模型后,可以从下面这个例子开始:

import asyncio
from companion_engine import CompanionBrain, Settings

async def main():
    async with CompanionBrain(
        storage="./output/brain.sqlite3",
        user_id="alice",
        settings=Settings.from_env(),
    ) as brain:
        if not any(c.id == "mika" for c in brain.characters()):
            brain.create_character(
                character_id="mika",
                name="Mika",
                persona="说话直接,带一点俏皮。关心对方,但不说空泛的安慰话。",
            )

        reply = await brain.chat(
            "mika", "记一下,我平时更喜欢喝茶。", request_id="message-1",
        )
        print(reply.text)        # 给用户看的回复
        print(reply.memory_ids)  # 这次保存的记忆 ID

asyncio.run(main())

下次打开同一个数据库,并使用相同的 user_id,就能继续原来的对话。重试同一条消息时沿用 request_id;发送新消息时要换一个新的 ID。同步应用可以使用 chat_sync()。

常用配置分成三层:

配置入口 用来控制
Settings 模型服务、凭据和模型侧限制。
BrainConfig 记忆检索、最近对话窗口、上下文预算和回复提示。
角色设置 角色性格、记忆写入策略,以及是否启用关系状态等行为。

创建角色不会自动调用模型或生成头像。通过默认 SDK 配置创建的角色,向量索引和摘要维护任务初始关闭,需要按需启用;已经保存的角色保留自己的配置。

→ SDK 使用指南 · 记忆、视觉与媒体参数

从一条消息到下一次对话

你的应用 / Agent 宿主
        │
        ▼
  准备上下文 ─── 角色设定 + 最近对话 + 检索到的证据
        │
        ▼
  生成回复 ───── SDK 调用你的模型,或由 MCP 宿主生成
        │
        ▼
  校验并提交 ─── 原始对话 + 有出处的记忆提议 + 可选状态更新
        │
        ▼
  本地 SQLite ── 下一轮或下次打开时继续使用

记忆写入支持自动保存、审核后保存和关闭三种模式。关闭事实写入,不等于停止保存对话历史;读取、写入和历史保留是不同的控制项。来源校验检查的是引用是否有出处,并不能保证模型对这段话的理解一定正确。

SDK 已提供可选的语音通话与动态视频适配,但不包含完整的 Anima 消费端应用、线上托管设施、计费系统或主动联系用户的服务。能力边界见架构文档。

接到现有的 Agent

如果你用的是 Claude Code、Claude Desktop 或 DeepSeek Harness,可以先生成本机的接入配置:

python -m pip install -e '.[mcp]'
companion --db ./output/host/brain.sqlite3 host-package ./output/hosts

接着按生成目录里的 START-HERE.md 操作。文件包含当前机器上的路径,因此换一台机器时应重新生成,不能把本机配置直接原样发给别人使用。接入后,回复仍由宿主自己的模型生成。

连接上 MCP,意味着宿主可以调用这些工具;不意味着所有聊天都会自动被记录。 宿主需要实际执行检索和保存操作,记忆才会参与对话。详见Claude / DeepSeek 接入指南和连接方式说明,含 ChatGPT。

如果你的程序需要通过本机 HTTP/MCP 访问,可以安装 .[http],再运行 companion http。companion settings 则只打开私有的服务配置表单。这两条命令本身都不会启动聊天网页。

只想聊天?直接体验 Anima

这个仓库主要面向开发者。如果你想直接体验角色陪伴,无需自己安装或配置模型,可以使用 Anima Lab:

官网与网页版 · iPhone / iPad · Android 下载

Anima Lab 的角色 Rina,身后是水族馆   Anima Lab 的角色 Sean

Rina 和 Sean 的展示图来自 Anima Lab 公开网站,用于介绍消费端产品;它们不是 SDK 预装的角色或能力。Android 通过官方页面提供 APK 下载。

继续阅读

以下详细开发文档目前以英文为主:

你想了解什么 看这里
聊天、配置、记忆审核和异常恢复 SDK 使用指南
记忆限制、看图、生图、语音合成与转写 SDK 参数与能力
Claude 和 DeepSeek Harness 的安装接入 宿主接入指南
MCP 工具、CLI 和底层接口 功能参考
检索公式、记忆整理和情绪变化 Brain Atlas 机制说明
Anima 架构的适配范围与实现边界 架构说明
向量索引与摘要维护任务 记忆维护
实时语音与动态视频通话 通话指南
参与开发、运行检查和准备发布 贡献指南

全部文档 · 验证记录 · 更新日志

项目状态与许可证

当前为 Alpha 版本,从源码安装。接口、协议和持久化测试通过,不代表所有模型的对话质量都经过验证。角色情绪是虚构状态模拟,不是对用户的心理评估。

本地存储也不等于本地推理:配置远程模型后,相应上下文会发送给该服务。user_id 用于数据隔离,不是登录或鉴权机制;部署前请阅读安全说明。

代码采用 MIT 许可证。Anima 品牌标识与角色图片适用单独的素材使用说明,也不是运行 SDK 的必要依赖。