AnimaWorks 深度指南：开源 Python 智能体框架，五层记忆体系让 AI 真正「记住」你

AI 智能体开发里有一个绕不过的矛盾：你的 AI 越聪明，它就越容易「忘事」。

上下文窗口 200k、1M token，够长了——但每次对话结束，一切归零。下一个用户打开 App，AI 不记得上一个用户说了什么；你的 AI 助手今天解决了一个复杂问题，明天同样的问题再来，它从头来过。

AnimaWorks（238 ⭐，Apache 2.0，v0.8.0）试图从根本上解决这个问题。它不是又一个”更大上下文窗口”方案，而是借鉴脑科学，给每个 AI 智能体配备五层记忆体系——情节记忆、语义记忆、程序记忆、工作记忆、人际记忆——并模拟人类睡眠时的”记忆巩固”机制，每天自动整理、每周合并重复、每月清除低效知识。

---

它到底是什么

AnimaWorks 的核心概念是 “Digital Anima”（数字灵魂体）——不是无状态的 API 调用工具，是有自己的身份、记忆、判断标准的持久化 AI 团队成员。

一个 Anima 的特征：

• 24/7 持续运行，有自主调度（每 30 分钟心跳巡逻，可配 Cron 任务）
• 封装式记忆，不与其他 Anima 共享上下文窗口，通过消息沟通
• 跨会话学习，每天夜间自动巩固当天的交互经验
• 组织层级，Manager Anima 可向下属 Anima 委派任务
• 主动遗忘，90 天未访问的低价值知识自动归档清除

官方哲学：“不完美的个体通过结构协作，胜过任何一个全知全能的单体 Actor。”

这和 LangChain（链式工具调用）、CrewAI（任务角色分工）、AutoGen（对话循环）的设计哲学都不同——那些框架的智能体本质上是无状态的，AnimaWorks 的 Anima 是有持续性身份的存在。

---

五层记忆体系：为什么这很重要

这是 AnimaWorks 与其他框架最核心的差异，值得单独拆解。

人类大脑的对应关系

AnimaWorks 记忆类型	对应人类记忆	存储内容	文件路径
工作记忆	前额叶工作区	LLM 当前上下文窗口	（运行时）
情节记忆	海马体日志	”什么时候发生了什么”	episodes/
语义记忆	大脑皮层知识库	抽象出的规律和知识	knowledge/
程序记忆	小脑技能存储	”怎么做某件事”的流程	procedures/
人际记忆	社交认知系统	每个用户的画像	shared/users/

记忆是怎么形成的：三阶段巩固

即时编码（会话边界）：Anima 空闲 ≥10 分钟时，自动将未记录的对话总结为情节日志，追加到 episodes/。

每日巩固（午夜 Cron）：Anima 回顾昨天的情节，提取新知识到 knowledge/，创建解决过的问题的处理流程到 procedures/，检测知识矛盾（用 NLI 模型验证）。

每周整合（周日 Cron）：合并重复知识、清理过期流程、压缩旧情节。“神经发生重组”——用 LLM 合并相似度高但冗余的知识块。

记忆如何被调用：双通道召回

自动召回（激活扩展）：每次推理前，框架自动检索并注入相关记忆：

• 最近 2 小时活动（BM25 搜索）
• 重要标记知识（[IMPORTANT] 标签）
• 关联知识（知识图谱 2 跳邻居，PageRank 权重）
• 当前任务板状态

主动召回：Anima 可以显式调用 search_memory 工具，查询特定历史记录或程序步骤。

主动遗忘：防止记忆污染

这是最反直觉也最重要的设计。不是”记得越多越好”，而是：

• 日常： 低访问频率知识打上衰减标记
• 每周： LLM 合并弱化的相似知识块
• 每月： 90 天未访问 + 访问次数 < 3 的知识彻底删除，归档到 archive/forgotten/

受保护的记忆（永不过期）：skills/ 目录下的技能文件、shared/users/ 用户画像、带 [IMPORTANT] 标签的所有记忆。

---

与主流框架对比

框架	记忆机制	持久性	学习能力	适用场景
LangChain	上下文窗口	无（每次调用独立）	无	工具链编排、RAG
CrewAI	会话级	无	无	角色分工任务
AutoGen	消息历史	无	无	多智能体对话
AnimaWorks	五层脑科学架构	永久（主动管理）	有（每日巩固）	持久化 AI 团队成员

AnimaWorks 不是 LangChain 的替代品——它们解决不同问题。需要快速接 API 做工具链的，LangChain 更轻。需要 AI 真正记住用户、积累经验、跨时间协作的，AnimaWorks 是目前开源里少有的选择。

---

支持的模型和生态

6 种执行模式（根据模型名前缀自动选择）：

模式	支持模型	特点
Claude Agent SDK	claude-*	最完整工具集成、MCP 支持
LiteLLM	OpenAI、Azure、Mistral、Bedrock、Ollama	多提供商通用路由
Gemini CLI	gemini/*	Google 模型原生支持
Codex CLI	codex/*	OpenAI Codex 系列
Cursor Agent	cursor/*	Cursor 专属模型
Basic	轻量级模型	最低 API 成本

内置角色默认模型：

• Engineer / Manager → Claude Opus 4.6（复杂推理）
• Writer / Researcher → Claude Sonnet 4.6（内容生成）
• Ops 监控 → vLLM GLM-4.7-flash（低成本例行任务）

向量数据库：ChromaDB（主要）+ Neo4j（实验性），嵌入模型 multilingual-e5-small，支持多语言。

图像生成：NovelAI（动漫风格）/ fal.ai Flux（写实）/ Meshy（3D 建模），自动生成 Anima 头像和表情变体。

平台集成：Slack（Socket Mode）、Discord、Chatwork、Notion、LINE、Telegram。

---

快速开始：三条路径

路径 A：60 秒 Docker 体验（推荐新手）

git clone https://github.com/xuiltul/animaworks.git
cd animaworks/demo
cp .env.example .env
# 编辑 .env，填入 ANTHROPIC_API_KEY=sk-ant-xxx
docker compose up

打开 http://localhost:18501，预加载了三个 Anima（Alex / Kai / Nova）和 3 天活动历史，可以直接体验。

支持四种预设配置：en-business / en-anime / ja-business / ja-anime。

路径 B：pip 安装（开发者首选）

# 需要 Python ≥ 3.12
pip install animaworks

# 或用 uv（更快）
uv add animaworks

初始化并启动：

# 创建工作目录
mkdir my-anima-project && cd my-anima-project

# 初始化默认配置
animaworks init

# 编辑配置（填入 API Key）
# ~/.animaworks/config.json 或当前目录 config.json

# 创建第一个 Anima
animaworks anima create --name alice --role researcher

# 启动服务
animaworks start
# 访问 http://localhost:18501

路径 C：从源码安装（贡献者 / 高级定制）

git clone https://github.com/xuiltul/animaworks.git
cd animaworks

# 使用 uv（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# 启动
uv run animaworks start

---

开发者完整工作流

第一步：配置 config.json

最小化配置（仅 Claude）：

{
  "llm": {
    "providers": {
      "anthropic": {
        "api_key": "sk-ant-xxx"
      }
    }
  },
  "animas": {
    "default_model": "claude-sonnet-4-6"
  }
}

多模型配置示例：

{
  "llm": {
    "providers": {
      "anthropic": { "api_key": "sk-ant-xxx" },
      "openai": { "api_key": "sk-openai-xxx" },
      "ollama": { "base_url": "http://localhost:11434" }
    }
  }
}

第二步：创建 Anima 并分配角色

# 创建研究员
animaworks anima create --name researcher --role researcher

# 创建工程师
animaworks anima create --name dev --role engineer

# 创建管理者（可向下属委派任务）
animaworks anima create --name manager --role manager

# 设置 manager 监管 researcher 和 dev
# 在 config.json 中配置 supervisor 字段

status.json（每个 Anima 的配置文件）示例：

{
  "model": "claude-sonnet-4-6",
  "supervisor": "manager",
  "max_tokens": 8192,
  "context_threshold": 0.8
}

第三步：通过 API 发送消息

import httpx

# 向 Anima 发送消息（SSE 流式响应）
async with httpx.AsyncClient() as client:
    async with client.stream(
        "POST",
        "http://localhost:18501/api/chat/researcher",
        json={"message": "分析一下这份市场报告的核心要点", "session_id": "user-001"}
    ) as response:
        async for line in response.aiter_lines():
            if line.startswith("data: "):
                print(line[6:], end="", flush=True)

第四步：查询 Anima 的记忆

# 搜索记忆
resp = httpx.get(
    "http://localhost:18501/api/memory/researcher/search",
    params={"query": "市场分析", "scope": "knowledge"}
)
print(resp.json())

# 读取特定记忆文件
resp = httpx.get(
    "http://localhost:18501/api/memory/researcher/read",
    params={"path": "knowledge/market_insights.md"}
)

第五步：设置定时任务（让 Anima 自主工作）

在 Anima 的 crons/ 目录创建 Markdown 文件：

## 每日数据摘要
schedule: 0 9 * * *
type: llm

搜索昨天积累的情节记忆，生成一份当天工作摘要，发送给 manager。

## 每周知识整理
schedule: 0 10 * * 0
type: llm

回顾本周的 procedures/ 目录，标记低效流程，建议改进方向。

第六步：CLI 常用命令

# 查看所有 Anima 状态
animaworks anima list

# 直接与 Anima 对话
animaworks chat researcher "上周我们讨论过哪些项目？"

# 查看日志
animaworks logs researcher

# 重建向量索引（记忆损坏时）
animaworks repair-rag --anima researcher --full

# 触发心跳（测试自主行为）
animaworks heartbeat researcher

---

REST API 速查

端点	功能
POST /api/chat/{name}	发送消息（SSE 流式）
GET /api/animas	列出所有 Anima
GET /api/memory/{name}/search	搜索记忆
POST /api/memory/{name}/write	写入记忆
GET /api/channels	列出共享频道
POST /api/channels/{name}/posts	发布到共享频道
GET /api/system/health	服务健康检查
WS /ws	实时 Dashboard
WS /ws/voice/{name}	语音对话（STT→LLM→TTS）

---

适用场景

✅ AnimaWorks 特别适合：

• 需要”记住用户”的 AI 助手：客服、个人助理、辅导系统——每次对话能知道上次聊了什么
• 长期自动化任务：定时情报收集、数据汇总、周报生成——Anima 持续学习，越用越准
• AI 角色扮演 / 虚拟角色：结合 NovelAI/fal.ai 图像生成，做有记忆的动漫数字人
• AI 团队协作系统：多个 Anima 分工（研究员、工程师、管理者），通过层级消息协作
• 私有知识库 + AI 问答：ChromaDB + 五层记忆，不只是 RAG，而是会”学习”的知识库

❌ 不太适合：

• 需要快速接 API 做一次性工具调用（LangChain 更轻）
• 对响应延迟极敏感的场景（记忆召回增加推理前处理时间）
• 超大规模部署（100+ Anima 以上，尚未有生产验证案例）

---

当前状态和局限

AnimaWorks 目前是 v0.8.0，2026 年 2 月才创建，活跃开发中（最新提交 2026-06-08），238 星，还是相对早期的项目。

已知问题（来自官方 security.md）：

• 凭据以明文存储在配置文件中（高优先级待修复）
• Socket 文件权限待加固
• 多智能体分布式垃圾邮件限制待完善

生产使用建议：目前更适合个人项目、实验性应用、原型验证。需要企业级部署的，建议等 v1.0 或评估是否有能力自行加固安全层。

---

AnimaWorks 做的事，核心可以用一句话概括：把 AI 智能体从”每次对话归零的工具”变成”有记忆、会学习、能在组织里协作的持久成员”。

这个方向本身是对的——当前大多数 AI 框架确实在用上下文窗口大小来”作弊”解决记忆问题，而不是真正建立记忆机制。AnimaWorks 的脑科学路径更复杂，但长期来看更扎实。

项目地址：github.com/xuiltul/animaworks

AnimaWorks: Open-Source Python Agent Framework with 5-Layer Memory That Actually Remembers

There’s a persistent contradiction in AI agent development: the smarter your AI, the more prone it is to forgetting.

200k, 1M token context windows — long enough — but every conversation ends at zero. The next user opens the app and the AI has no idea what the previous user said. Your AI assistant solves a complex problem today; the same problem tomorrow and it starts from scratch.

AnimaWorks (238 ⭐, Apache 2.0, v0.8.0) attacks this at the root. It’s not another “bigger context window” solution. It’s a neuroscience-inspired five-layer memory architecture — episodic, semantic, procedural, working, and interpersonal memory — with sleep-like consolidation running nightly, weekly deduplication, and monthly forgetting of low-utility knowledge.

---

Core Concept: “Digital Anima”

AnimaWorks’ fundamental unit is the Digital Anima — not a stateless API call tool, but a persistent AI team member with its own identity, memory, judgment standards, and autonomous schedule.

An Anima:

• Runs 24/7 with its own autonomous heartbeat (every 30 minutes by default) and Cron tasks
• Has encapsulated memory, communicating with other Animas through structured messages
• Learns across sessions through nightly memory consolidation
• Operates within org hierarchies: Manager Animas can delegate to subordinates
• Actively forgets: low-value knowledge auto-archives after 90 days without access

Official philosophy: “Imperfect individuals collaborating through structure outperform any single omniscient actor.”

---

The 5-Layer Memory System

This is AnimaWorks’ core differentiator from every other framework on the market.

Brain Correspondence

Memory Type	Human Equivalent	Stores	File Path
Working Memory	Prefrontal cortex workspace	Current LLM context window	(runtime)
Episodic Memory	Hippocampal logs	”What happened when”	episodes/
Semantic Memory	Cortical knowledge base	Abstracted patterns and lessons	knowledge/
Procedural Memory	Cerebellar skill storage	”How to do things”	procedures/
Interpersonal Memory	Social cognition system	Per-user profiles	shared/users/

Three-Stage Memory Consolidation

Immediate Encoding (Session Boundary): When an Anima is idle ≥10 minutes, it summarizes unrecorded turns into episode logs, appending to episodes/.

Daily Consolidation (Midnight Cron): The Anima reviews yesterday’s episodes, extracting new knowledge to knowledge/, creating resolved-problem procedures in procedures/, and running NLI model validation to detect contradictions.

Weekly Integration (Sunday Cron): Deduplication of similar knowledge, stale procedure cleanup, old episode compression, and “neurogenesis reorganization” — LLM-based merging of high-similarity redundant knowledge chunks.

Dual-Pathway Recall

Automatic Recall (Priming): Before each inference, the framework automatically retrieves and injects relevant memories:

• Recent 2-hour activity (BM25 search)
• Important flagged knowledge ([IMPORTANT] tags)
• Related knowledge (knowledge graph 2-hop neighbors, PageRank weighted)
• Current task board state

Intentional Recall: Animas can explicitly call search_memory for specific historical records or procedure steps.

Active Forgetting

The most counterintuitive design decision — “more memory is better” is wrong:

• Daily: Low-access-frequency knowledge gets decay markers
• Weekly: LLM merges weakened similar knowledge chunks
• Monthly: Knowledge with 90+ days no access AND <3 total accesses is deleted to archive/forgotten/

Protected forever: skills/ directory, shared/users/ profiles, anything tagged [IMPORTANT].

---

Framework Comparison

Framework	Memory	Persistence	Learning	Best For
LangChain	Context window	None	None	Tool chains, RAG
CrewAI	Session-level	None	None	Role-based task teams
AutoGen	Message history	None	None	Conversational loops
AnimaWorks	5-layer neuroscience	Permanent (managed)	Yes (nightly)	Persistent AI team members

AnimaWorks isn’t a LangChain replacement — they solve different problems. For quick API integrations and tool chains, LangChain is lighter. For AI that genuinely remembers users, accumulates experience, and collaborates across time, AnimaWorks is one of the few open-source options.

---

Supported Models

6 Execution Modes (auto-selected by model name prefix):

Mode	Models	Features
Claude Agent SDK	claude-*	Richest tool integration, MCP support
LiteLLM	OpenAI, Azure, Mistral, Bedrock, Ollama	Multi-provider routing
Gemini CLI	gemini/*	Native Google models
Codex CLI	codex/*	OpenAI Codex family
Cursor Agent	cursor/*	Cursor-specific models
Basic	Lightweight models	Minimal API cost

Default role models: Engineer/Manager → Claude Opus 4.6; Writer/Researcher → Claude Sonnet 4.6; Ops monitoring → vLLM GLM-4.7-flash.

---

Quick Start: Three Paths

Path A: 60-Second Docker Demo (Beginners)

git clone https://github.com/xuiltul/animaworks.git
cd animaworks/demo
cp .env.example .env
# Edit .env, add ANTHROPIC_API_KEY=sk-ant-xxx
docker compose up
# Open http://localhost:18501

Pre-loaded with three Animas (Alex / Kai / Nova) and 3 days of activity history.

Four preset styles: en-business / en-anime / ja-business / ja-anime.

Path B: pip Install (Developers)

# Requires Python ≥ 3.12
pip install animaworks
# or: uv add animaworks

# Initialize
animaworks init

# Create your first Anima
animaworks anima create --name alice --role researcher

# Start the server
animaworks start
# Visit http://localhost:18501

Path C: Source Build (Contributors)

git clone https://github.com/xuiltul/animaworks.git
cd animaworks
uv sync
uv run animaworks start

---

Developer Workflow

Minimal config.json (Claude only)

{
  "llm": {
    "providers": {
      "anthropic": { "api_key": "sk-ant-xxx" }
    }
  },
  "animas": {
    "default_model": "claude-sonnet-4-6"
  }
}

Send a message via API

import httpx

async with httpx.AsyncClient() as client:
    async with client.stream(
        "POST",
        "http://localhost:18501/api/chat/researcher",
        json={"message": "What do you remember about last week's project?", "session_id": "user-001"}
    ) as response:
        async for line in response.aiter_lines():
            if line.startswith("data: "):
                print(line[6:], end="", flush=True)

Schedule autonomous tasks

Create a Markdown file in crons/:

## Daily summary
schedule: 0 9 * * *
type: llm

Search yesterday's episodic memory and generate a daily work summary.
Send to manager when done.

## Weekly knowledge review
schedule: 0 10 * * 0
type: llm

Review this week's procedures/ directory.
Flag low-utility procedures for removal.

Key CLI commands

animaworks anima list                    # Status of all Animas
animaworks chat alice "What happened yesterday?"  # Direct chat
animaworks logs alice                   # View logs
animaworks repair-rag --anima alice --full  # Rebuild memory index
animaworks heartbeat alice              # Trigger autonomous cycle

---

When to Use AnimaWorks

Good fit:

• AI assistants that need to “remember users” — support, coaching, personal assistants
• Long-running automation — daily intelligence gathering, report generation
• AI characters / virtual companions — combine with NovelAI/fal.ai for memory-aware digital characters
• Multi-agent AI teams — researcher + engineer + manager collaborating through org hierarchy
• Private knowledge bases — not just RAG, but a knowledge base that learns

Not a great fit:

• One-shot API calls and simple tool chains (LangChain is lighter)
• Latency-critical scenarios (memory retrieval adds pre-inference overhead)
• Hyperscale deployment (100+ Animas — no production-verified cases yet)

---

Current Status

AnimaWorks is v0.8.0, created February 2026, actively maintained (latest commit June 8, 2026), 238 stars. Still early.

Known issues (from official security.md): Credentials stored in plaintext (high-priority fix pending), socket file permissions need hardening.

Recommendation: Best for personal projects, experimental apps, and prototypes today. For enterprise deployment, wait for v1.0 or be prepared to harden the security layer yourself.

---

AnimaWorks’ core bet: turn AI agents from “reset-every-conversation tools” into “persistent team members that remember, learn, and collaborate across time.”

The direction is right — most current frameworks are using context window size as a proxy for memory, not actually building memory mechanisms. The neuroscience path is more complex, but more structurally honest.

Project: github.com/xuiltul/animaworks