agentic-stack

在各类编码智能体工具之间保持一个可移植的记忆与技能层，让切换工具不会重置智能体的工作方式。

一个可移植的 .agent/ 文件夹（包含记忆 + 技能 + 协议），可接入 Claude Code、Cursor、Windsurf、OpenCode、OpenClaw、GitHub Copilot CLI、Google Gemini CLI、Hermes、Pi Coding Agent、Codex、Autohand Code CLI、Antigravity，或一个 DIY Python 循环——并且在切换时保留其知识。

它还包含一个本地数据层，让你可以从一个地方监控整套智能体：工具使用活动、定时任务运行、活跃智能体、令牌/成本估算、KPI 摘要、用户定义的资源类别，以及可直接截图的每日仪表盘。

它还能将已审核、已编辑的运行转化为本地飞轮构件：跟踪记录、上下文卡片、评估案例、可用于训练的 JSONL，以及无需训练模型或发送遥测数据即可获得的就绪度指标。

v0.19.1 新特性 — 记忆与升级修复

补丁版本。四项正确性修复：

• 回忆功能跳过已被取代的经验。 检索和渲染现在共享一个 superseded_by_map，因此回忆功能不会再在其替代品旁返回过时的指导。
• upgrade 命令将循环技能复制到正确路径。 新的 loop-* 技能曾被放置在 .agent/skills/skills/loop-x/；现在它们被放置在 .agent/skills/loop-x/。
• learn.py 中全面支持 UTF-8。 非 ASCII 字符的内容无论主机区域设置如何，都能正确打印和持久化。
• 检查课程是否已追加时无文件句柄泄漏。

有界智能体循环（v0.19.0）

可移植的循环契约位于 .agent/loops 目录下，并采用创建者 → 确定性验证者 → 独立检查者的生命周期：

agentic-stack loop init /path/to/your-project
agentic-stack loop validate /path/to/your-project
agentic-stack loop run ci-sweeper "make the failing test green" /path/to/your-project --yes
agentic-stack loop status /path/to/your-project

L2/L3 行动循环使用自有 Git 工作树、有限尝试次数/运行时间/输出/令牌预算、路径拒绝门控、可恢复检查点以及隐私安全的本地事件。

监督程序对子进程进行限制和审计；它并非操作系统沙箱。如需更强隔离性，请使用 harness 原生沙箱和审批机制。

调度程序应每次调用一个受限制的 loop run 命令，并在启动另一次运行前检查其退出状态。

早期版本——大脑内存桥（v0.18.0）、任务控制与课程撤回（v0.17.0）、安全项目升级（v0.16.0）、数据层与飞轮（v0.11.0）、harness 管理器（v0.9.0）——详见 CHANGELOG.md。

由 https://x.com/Av1dlive 开发

快速开始

macOS / Linux

# tap + install (one-time — both lines required)
brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack
brew install agentic-stack

# drop the brain into any project — the onboarding wizard runs automatically
cd your-project
agentic-stack claude-code
# or: cursor | windsurf | opencode | openclaw | copilot-cli | gemini | hermes | pi | codex | autohand-code | standalone-python | antigravity

Windows（PowerShell）

# clone + run the native installer
git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack
.\install.ps1 claude-code C:\path\to\your-project

已安装？

brew update && brew upgrade agentic-stack
agentic-stack dashboard

改为克隆？

git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack && ./install.sh claude-code         # mac / linux / git-bash
# or on Windows PowerShell: .\install.ps1 claude-code
# adapters: claude-code | cursor | windsurf | opencode | openclaw | copilot-cli | gemini | hermes | pi | codex | autohand-code | standalone-python | antigravity

安装完成后：管理已连接的内容

首次执行 ./install.sh <adapter> 后，可使用动词式子命令管理项目（install.sh 和 install.ps1 均适用）：

./install.sh dashboard           # TUI dashboard: health, verify, memory, team, skills, instances
./install.sh mission-control     # beta local web dashboard; Ctrl-C turns it off
./install.sh brain status        # optional external Brain CLI integration
./install.sh add cursor          # add a second adapter (Claude Code + Cursor in same repo)
./install.sh status              # one-screen view: which adapters, brain stats
./install.sh doctor              # read-only audit; green / yellow / red per adapter
./install.sh manage              # interactive TUI: header pane + menu loop for add/remove/audit
./install.sh transfer            # onboarding-style wizard: export/import memory as a curl bridge
./install.sh upgrade --dry-run   # preview safe .agent infrastructure refresh
./install.sh upgrade --yes       # copy latest harness/memory/tools + new skills
./install.sh sync-manifest       # rebuild .agent/skills/_manifest.jsonl from SKILL.md frontmatter
./install.sh remove cursor       # confirm prompt + delete; no quarantine, no undo

PowerShell 使用相同的动词，例如 .\install.ps1 dashboard。

可选：外部 Brain 集成

codejunkie99/brain 是一个基于 git 的长期记忆二进制文件和 MCP 服务器。agentic-stack 现在将其视为可选的外部记忆层，而非引入其 Rust 工作区。

请先安装 Brain：

brew install codejunkie99/tap/brain

然后从项目中检查或连接它：

agentic-stack brain status
agentic-stack brain onboard --agents codex,cursor --yes
agentic-stack brain ask "auth decisions"
agentic-stack brain note "Use PKCE for local OAuth flows."
agentic-stack brain mcp-command

已安装的 .agent/ 项目还会获得 python3 .agent/tools/brain_bridge.py 和一个 brain 种子技能，以便宿主代理在任务需要跨工具长期记忆时，能够查询或写入 Brain 内存。

直接运行 ./install.sh（不带参数）会在新项目上打开一个多选向导——勾选所有你实际使用的工具，按回车键，每个选中的工具都会被安装。该向导会自动检测磁盘上已存在的工具，并预先勾选它们。对于已存在 install.json 的项目，直接运行交互式 ./install.sh 会打开控制面板。在非 TTY shells（如 CI 环境）中，它会保持脚本安全，只打印可用的子命令，而不打开 TUI。

从 v0.9 之前的版本升级？请先运行 ./install.sh doctor——它会根据磁盘上的适配器信号合成 install.json，以便新的后端能够跟踪它们。不进行迁移就直接覆盖安装会导致之前的安装文件被孤立。

在 brew upgrade 之后升级已安装的项目？请先在项目中运行 agentic-stack upgrade --dry-run，然后运行 agentic-stack upgrade --yes 以仅刷新由框架管理的 .agent 基础设施（harness/**/*.py、顶级 memory/*.py、tools/*.py、生成的技能索引以及新的技能目录）。它不会重写 CLAUDE.md、.claude/settings.json、个人/语义/情景/工作记忆、候选内容或现有技能目录。如果 _manifest.jsonl 与已安装的 SKILL.md 文件不同步，可使用 agentic-stack sync-manifest 作为修复命令。

入职向导

如果你直接运行 ./install.sh（不带适配器名称），向导会从工具多选步骤开始：它会列出所有 13 个适配器，预先勾选任何在磁盘上检测到的适配器，你通过空格键选中并按回车键确认后，每个选中的适配器都会被安装。安装完成后，会进入偏好设置流程。

如果你直接运行 ./install.sh <adapter>，则只会运行偏好设置流程。

无论哪种方式，偏好设置步骤都会填充 .agent/memory/personal/PREFERENCES.md——AI 在每个会话开始时首先读取的文件，并在 .agent/memory/.features.json 写入一个功能切换文件。

六个偏好问题（每个都可以按回车键跳过）：

问题	默认值
我该如何称呼你？	(跳过)
主要语言？	unspecified
解释风格？	concise
测试策略？	test-after
提交消息风格？	conventional commits
代码审查深度？	critical issues only

外加一个可选功能步骤（默认关闭，需手动选择启用）：

功能	默认值
启用 FTS 内存搜索 [BETA]	no
启用 tldraw 可视化画布 [BETA]	no

标志：

agentic-stack claude-code --yes          # accept all defaults, beta off (CI/scripted)
agentic-stack claude-code --reconfigure  # re-run the wizard on an existing project

随时编辑 .agent/memory/personal/PREFERENCES.md 以优化你的约定，或编辑 .agent/memory/.features.json 来切换功能开关。

迁移向导

通过类似入职流程的 TUI，将一个项目智能体的可移植部分迁移到 Codex、Cursor、Windsurf 或纯终端项目中：

./install.sh transfer

该向导能将自然语言意图转化为迁移计划，让您可以查看目标载体和内存范围，在导出前屏蔽类似机密的内容，并生成一行curl命令供下一环境运行。

对于move my memory指令，它包含偏好设置、已接受的经验、技能、工作内存、情景/历史日志以及候选经验。导入器会解包该 bundle，验证其SHA-256摘要，合并偏好设置和已接受的经验，复制选定的技能，恢复选定的内存文件，并安装匹配的适配器文件。

对于脚本化交接：

./install.sh transfer export --intent "move my preferences and lessons into Codex" --print-curl
./install.sh transfer import --payload-file transfer.txt --sha256 <digest> --target codex

审核协议（host-agent 命令行界面）

夜间运行的 auto_dream.py 周期仅暂存候选经验。它不会标记任何已接受内容，也不会修改语义记忆。您的 host agent 会在会话中执行审核：

# list pending candidates, sorted by priority
python3 .agent/tools/list_candidates.py

# accept with rationale (required)
python3 .agent/tools/graduate.py <id> --rationale "evidence holds, matches PREFERENCES"

# reject with reason (required); preserves decision history
python3 .agent/tools/reject.py <id> --reason "too specific to generalize"

# requeue a previously-rejected candidate
python3 .agent/tools/reopen.py <id>

# retract an accepted lesson from future recall/context (append-only audit)
python3 .agent/tools/retract_lesson.py <lesson_id> --rationale "obsolete after migration"

已毕业的课程会保存到 semantic/lessons.jsonl（事实来源）中，并渲染为 semantic/LESSONS.md。被拒绝的候选课程会保留完整的决策历史，以便清晰追踪反复出现的问题，而非视为新问题。已撤回的课程会以 status=retracted 的状态保留在历史记录中，但不会纳入主动召回范围。

完整的生命周期请参见 docs/architecture.md。

---

项目简介

所有指南都会展示文件夹结构。本仓库不仅提供文件夹结构，还包含实际需要放入其中的文件：一个可运行的便携式智能体，具备九项基础技能、四个记忆层、强制权限控制、夜间暂存周期、宿主智能体审核工具，以及适用于多种运行环境的适配器。

• 记忆系统 — working/、episodic/、semantic/、personal/。每个记忆层都有其独立的保留策略。支持查询感知检索（显著性 × 相关性）；夜间自动压缩为可审核的候选内容。
• 审核协议 — auto_dream.py 以机械方式暂存候选课程。宿主智能体通过 CLI 工具（graduate.py、reject.py、reopen.py）对其进行审核，并在提交决策时提供必要的理由。无需无人值守推理，不与任何服务提供商绑定。
• 技能体系 — 采用渐进式披露机制。始终加载轻量级清单；仅当触发条件与任务匹配时，才加载完整的 SKILL.md 文件。每项技能均配备自我重写钩子。内置的 design-md 技能可指导智能体将根目录下的 DESIGN.md 用作 UI 和 Google Stitch 工作流的可视化事实来源。
• 协议规范 — 包含类型化工具模式、工具调用前钩子强制执行的 permissions.md，以及子智能体的委托契约。
• 数据层 — 在所有共享 .agent/ 的运行环境中提供仅限本地的仪表板导出功能：智能体事件、定时任务时间线、KPI 摘要、令牌/成本估算、任务分类、运行环境组合、dashboard.html 以及每日报告交接。
• 数据飞轮 — 经过批准和脱敏的运行记录可转化为跟踪记录、上下文卡片、评估用例、可用于训练的 JSONL 数据以及就绪度指标，无需训练模型或发送遥测数据。

版本发布与更新日志

各版本的发布说明详见 CHANGELOG.md。最新发布版本、问题修复、新增功能、升级路径等信息均收录于此。

记忆搜索 [BETA]

可选择启用 FTS5 关键词搜索，对所有记忆文档进行检索：

# enable during onboarding (or set manually in .agent/memory/.features.json)
python3 .agent/memory/memory_search.py "deploy failure"
python3 .agent/memory/memory_search.py --status
python3 .agent/memory/memory_search.py --rebuild

如果已安装 ripgrep (rg)，则会回退使用它，否则使用 grep——两者均限制为 .md / .jsonl 文件，因此源文件绝不会污染结果。

索引存储在 .agent/memory/.index/ 目录下，并已添加到 git 忽略列表中。

仓库布局

.agent/                         # the portable brain (same across harnesses)
├── AGENTS.md                   # the map
├── harness/                    # conductor + hooks (standalone path)
│   └── hooks/
│       ├── claude_code_post_tool.py  # rich PostToolUse logging (v0.8+)
│       ├── pre_tool_call.py    # permissions enforcement
│       ├── post_execution.py   # log_execution() entry point
│       └── on_failure.py       # failure write + repeated-failure rewrite flag
├── memory/                     # working / episodic / semantic / personal
│   ├── auto_dream.py           # staging-only dream cycle
│   ├── cluster.py              # content clustering + pattern extraction
│   ├── promote.py              # stage candidates
│   ├── validate.py             # heuristic prefilter (length + exact duplicate)
│   ├── review_state.py         # candidate lifecycle + decision log
│   ├── render_lessons.py       # lessons.jsonl → LESSONS.md
│   └── memory_search.py        # [BETA] FTS5 search (opt-in)
├── skills/                     # _index.md + _manifest.jsonl + SKILL.md files
├── protocols/                  # permissions + tool schemas + delegation
│   └── hook_patterns.json      # user-owned high/medium-stakes regex (v0.8+)
└── tools/                      # host-agent CLI + memory_reflect + skill_loader
    ├── learn.py                # one-shot lesson teaching (stage + graduate)
    ├── recall.py               # surface lessons relevant to an intent
    ├── show.py                 # colorful brain-state dashboard
    ├── data_layer_export.py    # local cross-harness dashboard/data export
    ├── data_flywheel_export.py # approved runs -> traces/cards/evals/JSONL
    ├── brain_bridge.py         # bridge to external Brain CLI/MCP memory
    ├── list_candidates.py
    ├── graduate.py
    ├── reject.py
    ├── reopen.py
    └── retract_lesson.py       # append-only semantic lesson retraction

adapters/                       # one small shim per harness, each with adapter.json manifest
├── claude-code/   (CLAUDE.md + settings.json hooks — $CLAUDE_PROJECT_DIR wired, closes #18)
├── copilot-cli/   (AGENTS.md + .github/instructions/ + .github/hooks/ + .github/skills/ mirror)
├── cursor/        (.cursor/rules/*.mdc)
├── gemini/        (gemini.md + .gemini/skills mirror)
├── windsurf/      (.windsurf/rules/*.md + legacy .windsurfrules)
├── opencode/      (AGENTS.md + opencode.json)
├── openclaw/      (AGENTS.md + system-prompt include; auto-registers per-project agent)
├── hermes/        (AGENTS.md)
├── pi/            (AGENTS.md + .pi/skills symlink)
├── codex/         (AGENTS.md + .agents/skills symlink)
├── autohand-code/ (AGENTS.md + .autohand/skills symlink)
├── standalone-python/  (DIY conductor entrypoint)
└── antigravity/   (ANTIGRAVITY.md)

harness_manager/                # v0.9.0 manifest-driven Python backend
├── schema.py                   # adapter.json validator (path-safe on POSIX + Windows)
├── install.py                  # applies file entries per merge_policy
├── state.py                    # install.json read/write with fcntl/msvcrt locking
├── doctor.py                   # read-only audit + pre-v0.9 migration synthesis
├── remove.py                   # safe uninstall with shared-file detection + ownership handoff
├── dashboard_tui.py            # project dashboard for health/verify/memory/team/skills/instances
├── mission_control.py          # beta local web dashboard entrypoint
├── brain.py                    # optional external Brain CLI integration
├── mission_control_collectors.py
├── mission_control_render.py
├── mission_control_server.py
├── mission_control_static.py
├── post_install.py             # named built-ins (openclaw_register_workspace)
├── manage_tui.py               # interactive menu loop for add/remove/audit
├── transfer_tui.py             # onboarding-style memory transfer wizard
├── transfer_plan.py            # natural-language target/scope planning
├── transfer_bundle.py          # export/import bundle codec + merge logic
├── skill_manifest.py           # rebuilds skills/_manifest.jsonl from SKILL.md
├── upgrade.py                  # safe .agent infrastructure refresh
└── cli.py                      # argparse dispatcher for install.sh / install.ps1

docs/                           # architecture, getting-started, per-harness
schemas/data-layer/             # local dashboard/event schemas
examples/data-layer/            # sanitized data-layer shapes
schemas/flywheel/               # data-flywheel artifact schemas
examples/flywheel/              # sanitized approved-run examples
install.sh                      # mac / linux / git-bash installer (thin Python dispatcher)
install.ps1                     # Windows PowerShell installer (thin Python dispatcher)
Formula/agentic-stack.rb        # Homebrew formula
CHANGELOG.md                    # per-version release notes (v0.1.0 onward)
onboard.py                      # onboarding wizard entry point
onboard_features.py             # .features.json read/write
onboard_ui.py                   # ANSI palette, banner, clack-style layout
onboard_widgets.py              # arrow-key prompts (text, select, confirm)
onboard_render.py               # answers → PREFERENCES.md content
onboard_write.py                # atomic file write with backup
test_claude_code_hook.py        # hook validation suite (54 checks)
verify_codex_fixes.py           # v0.8.0 regression checks (33 checks)

支持的集成工具

集成工具	读取的配置文件	钩子支持
Claude Code	CLAUDE.md + .claude/settings.json	支持（PostToolUse、Stop）
GitHub Copilot CLI	AGENTS.md + .github/instructions/*.instructions.md	支持（postToolUse、sessionEnd）
Cursor	.cursor/rules/*.mdc	不支持（需手动调用反思）
Google Gemini CLI	gemini.md + .gemini/skills/	不支持（需手动调用反思）
Windsurf	.windsurfrules	不支持（需手动调用反思）
OpenCode	AGENTS.md + opencode.json	部分支持（权限规则）
OpenClaw	AGENTS.md（自动注入）+ 每个项目使用 openclaw agents add --workspace	因分支而异
Hermes Agent	AGENTS.md（与agentskills.io兼容）	部分支持（自有内存）
Pi Coding Agent	AGENTS.md + .pi/skills/ + .pi/extensions/	支持（tool_result 事件）
Codex	AGENTS.md + .agents/skills/	不支持（需手动调用反思）
Autohand Code CLI	AGENTS.md + .autohand/skills/	不支持（需手动调用反思）
独立 Python	run.py（任何LLM）	支持（完全控制）
Antigravity	ANTIGRAVITY.md	支持（系统上下文）

基础技能

• skillforge — 从重复模式中创建新技能
• memory-manager — 运行反思周期，筛选候选经验教训
• git-proxy — 所有git操作，附带安全约束
• debug-investigator — 重现 → 隔离 → 假设 → 验证
• deploy-checklist — 隔离 staging 环境与生产环境的防护栏
• design-md — 使用类 Google Stitch 风格的 DESIGN.md 文件作为可移植的设计系统上下文，适用于UI、前端和组件开发工作
• data-layer — 跨集成工具导出本地仪表板数据、定时任务时间线、关键绩效指标（KPIs）和每日报告
• data-flywheel — 将已批准的运行转化为上下文卡片、评估、脱敏追踪记录、可用于训练的JSONL格式数据以及飞轮指标
• tldraw — 可选的测试版技能，用于实时画布图表，在 .agent/skills/tldraw/ 目录下有本地快照存储

其复合效应机制

1. 技能会将每个操作记录到情景记忆中。
2. auto_dream.py 将重复出现的模式聚类为候选经验。
3. 宿主代理通过 graduate.py / reject.py 对候选经验进行审核。
4. 通过审核的经验会追加到 lessons.jsonl；LESSONS.md 会重新渲染。
5. 未来的会话会自动加载与查询相关的已采纳经验。
6. on_failure 会标记 14 天内失败 3 次及以上的技能，以便进行重写。
7. git log .agent/memory/ 成为代理的自传。
8. 数据层导出功能将本地活动转换为可用于仪表板的监控数据。
9. 经过批准和编辑的运行可导出为 .agent/flywheel/ 工件，用于检索、评估、提示词精简以及可选的未来适配器开发。

将已批准的运行导出到数据飞轮

将经过人工审核和脱敏处理的运行存入：

.agent/flywheel/approved-runs.jsonl

然后运行：

python3 .agent/tools/data_flywheel_export.py

输出内容保存在 .agent/flywheel/exports/<date>/ 目录下：

• trace-records.jsonl
• training-examples.jsonl
• eval-cases.jsonl
• context-cards/<domain>/<workflow>.md
• flywheel-metrics.json

此功能仅在本地运行，且与模型无关。它会生成可直接用于训练的工件，但不会训练模型。

详见 docs/data-flywheel.md。

每晚运行暂存周期

crontab -e
0 3 * * * python3 /path/to/project/.agent/memory/auto_dream.py >> /path/to/project/.agent/memory/dream.log 2>&1

auto_dream.py 会以绝对路径解析路径，并仅执行机械性的文件操作（聚类、暂存、预过滤、衰减）。不涉及 git 提交，不连接网络，不进行推理——可放心无人值守运行。

监控你的智能体套件

为所有写入同一 .agent/ 大脑的载体生成本地仪表盘：

python3 .agent/tools/data_layer_export.py --window 30d --bucket day

或者让注入的 data-layer 技能传递用户的话语：

python3 .agent/tools/data_layer_export.py show me last 7 days by hour

输出内容将保存至 .agent/data-layer/exports/<date>/ 目录，包括 dashboard.html、dashboard.tui.txt 和 daily-report.md 文件。该命令还会在您的编码工具内直接显示引导式终端仪表盘。可选的本地输入允许您添加计划运行和分类：

.agent/data-layer/cron-runs.jsonl
.agent/data-layer/category-rules.json
.agent/data-layer/harness-events.jsonl

使用此功能可按日跟踪定时任务、活跃智能体、按小时/日/周/月估算的令牌用量/成本、Claude/Hermes/OpenClaw/Codex等工具的使用占比、成功/错误率、运行频率、工作流覆盖范围，以及用户定义的类别（如个人、管理、工作、财务和编码）。数据层仅本地存储；截图交付需用户明确批准并通过用户配置的渠道进行。

参见 docs/data-layer.md。

许可证

Apache 2.0 — 详见 LICENSE。

致谢

基于@AV1DLIVE的文章 "The Agentic Stack" 开发 — 关注以获取更新和合作信息。 使用Minimax-M2.7在Claude Code工具中编写代码；由Macroscope和Codex进行PR审核。 借鉴了Gstack、Claude Code的内存系统以及智能体工程社区中的对话模式。构建此项目的假设是工具无关性才是关键。

星标历史