Baka Agent

面向个人长期协作的记忆优先聊天 Agent。

Baka Agent 把一次对话当作可持续演进的工作上下文：它既能完成普通聊天与工具调用，也能在明确作用域、授权规则和审计证据约束下，检索和复用长期记忆。项目当前重点是把“聊天 Agent”从单轮回答器扩展为可解释、可验证的个人工作伙伴。

核心能力

• 多渠道对话：内置本机 Web Chat，可按配置接入 Telegram、QQ 等渠道。
• 记忆优先：短期上下文、Markdown 长期记忆和向量检索协作，减少重复解释。
• 多作用域记忆：Memory2 提供 principal、scope、资源类型和标签授权；未授权读取默认拒绝，并保留授权、撤销和检索审计证据。
• 主动工作流：可按明确配置执行信息订阅、提醒和后台任务，不把主动行为伪装成用户消息。
• 插件与工具：通过版本化插件快照扩展工具、技能和 MCP 能力，候选加载失败时保留上一个可用版本。
• 可恢复运行：会话、记忆和关键运行状态分开保存；迁移、备份和回滚有明确的状态边界。

设计视角

消息渠道 / Web Chat
          │
          ▼
     Baka Agent Runtime
          │
  ┌───────┼────────┐
  ▼       ▼        ▼
对话层   记忆层    工具与插件层
          │
          ▼
Principal + Scope + Grant Policy
          │
          ▼
只注入已获授权、与当前问题相关的长期事实

这里的授权系统只约束“哪些记忆可以被定向召回”，不是通用 IAM，也不承担账户、组织或资源管理职责。

快速开始

需要 Python 3.12 和 uv。

git clone https://github.com/fxl112233/baka-agent.git
cd baka-agent
uv venv
uv pip install -r requirements.txt
uv run python main.py

启动后打开：

• 设置中心：http://127.0.0.1:6321
• 本机 Web Chat：http://127.0.0.1:6322

首次使用可以在设置中心填写 DeepSeek、阿里云百炼或其他 OpenAI Chat Completions 兼容 Provider 的配置。不要提交真实的 API Key、config.toml、workspace 数据库或会话日志。

也可以从配置模板开始：

# Windows PowerShell
Copy-Item config.example.toml config.toml

# macOS / Linux
cp config.example.toml config.toml

随后在 config.toml 中填写模型与 API Key。模板默认将运行数据放在 ~/.baka-agent/workspace，便于与其他项目隔离。

开发方式

日常开发与上传：

git add .
git commit -m "feat: describe the change"
git push

建议一个功能对应一个分支和一组可复现测试；涉及记忆隔离、授权共享、迁移或持久化状态时，再运行对应的合同测试与 Gate。运行时 workspace 不属于 Git worktree，切换分支或清理代码时不要删除其中的会话和记忆数据。

当前方向

1. 完善 Memory2 的多作用域隔离、定向共享与可审计撤销。
2. 用注入使用率和跨作用域迁移增益评测，验证记忆确实帮助回答而非仅增加上下文。
3. 将主动工作流、插件和工具调用收敛到可恢复、可观察的运行边界。

兼容性说明

为了兼容既有 runtime、插件和 workspace，代码中仍保留部分历史内部标识，例如 AKASHIC_WORKSPACE、.akashic 目录和 akashic 模块名。它们是兼容层，不代表项目对外名称；新配置和用户可见身份使用 Baka Agent。

许可证与来源

Baka Agent 包含基于 Akashic Agent 修改的代码。原版权声明和 MIT License 完整保留在 LICENSE 文件中。