agentic-stack-portable-agent-memory

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agentic-stack-portable-agent-memory

Skill by ara.so — AI Agent Skills collection.

由ara.so开发的Skill — AI Agent技能集合。

What It Does

功能介绍

agentic-stack creates a portable

.agent/

folder that maintains memory, skills, and protocols across different AI coding harnesses (Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Copilot CLI, Gemini, Hermes, Pi, Codex, Antigravity). When you switch tools, your agent keeps its knowledge, preferences, and accumulated context.

It includes:

Memory layers: personal, semantic, episodic, working memory
Skills system: reusable capabilities with manifest tracking
Data layer: monitor harness activity, token/cost estimates, KPI summaries
Data flywheel: turn approved runs into training artifacts
Brain integration: optional git-backed long-term memory
Harness manager: TUI for managing multiple adapters simultaneously

agentic-stack 创建一个可移植的

.agent/

文件夹，在不同AI编码工具（Claude Code、Cursor、Windsurf、OpenCode、OpenClaw、Copilot CLI、Gemini、Hermes、Pi、Codex、Antigravity）之间维护记忆、技能和协议。当你切换工具时，你的Agent会保留其知识、偏好和积累的上下文。

它包含以下组件：

记忆层：个人记忆、语义记忆、情景记忆、工作记忆
技能系统：可复用能力及清单追踪
数据层：监控工具活动、token/成本估算、KPI汇总
数据飞轮：将已批准的运行记录转化为训练工件
Brain集成：可选的基于Git的长期记忆
工具管理器：用于同时管理多个适配器的TUI

Installation

安装方法

macOS / Linux

bash

undefined

bash

undefined

Tap and install (both lines required)

点击并安装（两行都需要执行）

brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack brew install agentic-stack

Install into your project

安装到你的项目中

cd your-project agentic-stack claude-code

undefined

cd your-project agentic-stack claude-code

undefined

Windows (PowerShell)

Windows（PowerShell）

powershell

git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack
.\install.ps1 claude-code C:\path\to\your-project

powershell

git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack
.\install.ps1 claude-code C:\path\to\your-project

Clone Method

克隆安装法

bash

git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack
./install.sh claude-code

bash

git clone https://github.com/codejunkie99/agentic-stack.git
cd agentic-stack
./install.sh claude-code

Upgrade Existing Installation

升级现有安装

bash

brew update && brew upgrade agentic-stack
cd your-project
agentic-stack upgrade --dry-run
agentic-stack upgrade --yes

bash

brew update && brew upgrade agentic-stack
cd your-project
agentic-stack upgrade --dry-run
agentic-stack upgrade --yes

Available Adapters

可用适配器

```
claude-code
```
- Anthropic Claude Code
```
cursor
```
- Cursor IDE
```
windsurf
```
- Windsurf
```
opencode
```
- OpenCode
```
openclaw
```
- OpenClaw
```
copilot-cli
```
- GitHub Copilot CLI
```
gemini
```
- Google Gemini CLI
```
hermes
```
- Hermes
```
pi
```
- Pi Coding Agent
```
codex
```
- Codex
```
standalone-python
```
- DIY Python loop
```
antigravity
```
- Antigravity

```
claude-code
```
- Anthropic Claude Code
```
cursor
```
- Cursor IDE
```
windsurf
```
- Windsurf
```
opencode
```
- OpenCode
```
openclaw
```
- OpenClaw
```
copilot-cli
```
- GitHub Copilot CLI
```
gemini
```
- Google Gemini CLI
```
hermes
```
- Hermes
```
pi
```
- Pi Coding Agent
```
codex
```
- Codex
```
standalone-python
```
- DIY Python循环
```
antigravity
```
- Antigravity

Key Commands

核心命令

Project Management

项目管理

bash

undefined

bash

undefined

Interactive dashboard

交互式仪表盘

agentic-stack dashboard

Web-based mission control (beta)

基于Web的任务控制（测试版）

agentic-stack mission-control

Check adapter status

检查适配器状态

agentic-stack status

Audit installation health

检查安装健康状况

agentic-stack doctor

Interactive adapter manager

交互式适配器管理器

agentic-stack manage

Add additional adapter

添加额外适配器

agentic-stack add cursor

Remove adapter

移除适配器

agentic-stack remove cursor

undefined

agentic-stack remove cursor

undefined

Upgrade & Sync

升级与同步

bash

undefined

bash

undefined

Preview infrastructure updates

预览基础设施更新

agentic-stack upgrade --dry-run

Apply updates (preserves memory and custom skills)

应用更新（保留记忆和自定义技能）

agentic-stack upgrade --yes

Rebuild skill manifest

重建技能清单

agentic-stack sync-manifest

undefined

agentic-stack sync-manifest

undefined

Brain Integration (Optional)

Brain集成（可选）

bash

undefined

bash

undefined

Install Brain CLI

安装Brain CLI

brew install codejunkie99/tap/brain

Check Brain status

检查Brain状态

agentic-stack brain status

Onboard project to Brain

将项目接入Brain

agentic-stack brain onboard --agents codex,cursor --yes

Query Brain memory

查询Brain记忆

agentic-stack brain ask "auth decisions"

Write to Brain memory

写入Brain记忆

agentic-stack brain note "Use PKCE for local OAuth flows."

Get MCP command

获取MCP命令

agentic-stack brain mcp-command

undefined

agentic-stack brain mcp-command

undefined

Memory Transfer

记忆迁移

bash

undefined

bash

undefined

Export/import memory between projects

在项目间导出/导入记忆

agentic-stack transfer

undefined

agentic-stack transfer

undefined

Project Structure

项目结构

After installation, your project will have:

.agent/
├── memory/
│   ├── personal/PREFERENCES.md    # User preferences (read first)
│   ├── semantic/                  # Conceptual knowledge
│   ├── episodic/                  # Session history
│   ├── working/                   # Active context
│   └── .features.json             # Feature toggles
├── skills/
│   ├── _manifest.jsonl            # Skill registry
│   ├── brain/                     # Brain integration skill
│   ├── data-layer/                # Harness monitoring
│   ├── data-flywheel/             # Training artifact export
│   ├── design-md/                 # DESIGN.md workflows
│   └── tldraw/                    # Visual canvas (opt-in)
├── tools/
│   └── brain_bridge.py            # Brain API wrapper
├── harness/
│   └── adapters/                  # Adapter-specific configs
└── install.json                   # Installed adapters manifest

安装完成后，你的项目将包含以下结构：

.agent/
├── memory/
│   ├── personal/PREFERENCES.md    # 用户偏好（优先读取）
│   ├── semantic/                  # 概念知识
│   ├── episodic/                  # 会话历史
│   ├── working/                   # 活跃上下文
│   └── .features.json             # 功能开关
├── skills/
│   ├── _manifest.jsonl            # 技能注册表
│   ├── brain/                     # Brain集成技能
│   ├── data-layer/                # 工具监控
│   ├── data-flywheel/             # 训练工件导出
│   ├── design-md/                 # DESIGN.md工作流
│   └── tldraw/                    # 可视化画布（可选启用）
├── tools/
│   └── brain_bridge.py            # Brain API包装器
├── harness/
│   └── adapters/                  # 适配器专属配置
└── install.json                   # 已安装适配器清单

Configuration

配置方法

Initial Setup (Onboarding Wizard)

初始设置（引导向导）

The wizard populates

.agent/memory/personal/PREFERENCES.md

bash

undefined

向导会填充

.agent/memory/personal/PREFERENCES.md

文件：

bash

undefined

Accept all defaults (CI mode)

接受所有默认设置（CI模式）

agentic-stack claude-code --yes

Re-run wizard on existing project

在现有项目中重新运行向导

agentic-stack claude-code --reconfigure


Wizard questions:
1. What should I call you? *(optional)*
2. Primary language(s)? *(default: unspecified)*
3. Explanation style? *(default: concise)*
4. Test strategy? *(default: test-after)*
5. Commit message style? *(default: conventional commits)*
6. Code review depth? *(default: critical issues only)*

Optional features (off by default):
- FTS memory search `[BETA]`
- tldraw visual canvas `[BETA]`

agentic-stack claude-code --reconfigure


向导问题：
1. 怎么称呼你？*（可选）*
2. 主要使用的语言？*（默认：未指定）*
3. 解释风格？*（默认：简洁）*
4. 测试策略？*（默认：事后测试）*
5. 提交信息风格？*（默认：规范提交）*
6. 代码审查深度？*（默认：仅关键问题）*

可选功能（默认关闭）：
- FTS记忆搜索 `[BETA]`
- tldraw可视化画布 `[BETA]`

Manual Preference Editing

手动编辑偏好

Edit

.agent/memory/personal/PREFERENCES.md

directly:

markdown

---
name: Alex
languages: [Python, TypeScript]
explanation_style: detailed
test_strategy: test-first
commit_style: conventional commits
review_depth: thorough
---

直接编辑

.agent/memory/personal/PREFERENCES.md

：

markdown

---
name: Alex
languages: [Python, TypeScript]
explanation_style: detailed
test_strategy: test-first
commit_style: conventional commits
review_depth: thorough
---

Personal Preferences

个人偏好

I prefer async/await over callbacks. Use descriptive variable names. Always include error handling for network requests.

undefined

我更喜欢async/await而非回调函数。使用描述性变量名。网络请求始终包含错误处理。

undefined

Feature Toggles

功能开关

Edit

.agent/memory/.features.json

json

{
  "fts_search": false,
  "tldraw": false
}

编辑

.agent/memory/.features.json

：

json

{
  "fts_search": false,
  "tldraw": false
}

Working with Memory Layers

记忆层使用方法

Personal Memory

个人记忆

bash

undefined

bash

undefined

View preferences

查看偏好设置

cat .agent/memory/personal/PREFERENCES.md

Add personal context

添加个人上下文

echo "## Code Style\n\nPrefer functional composition over inheritance." >> .agent/memory/personal/PREFERENCES.md

undefined

echo "## 代码风格\n\n优先使用函数式组合而非继承。" >> .agent/memory/personal/PREFERENCES.md

undefined

Semantic Memory

语义记忆

python

undefined

python

undefined

.agent/memory/semantic/architecture_decisions.md

""" Document lasting project knowledge """

undefined

""" 记录项目长期知识 """

undefined

Episodic Memory

情景记忆

Automatically managed by harness; tracks session history and decisions.

由工具自动管理；追踪会话历史和决策记录。

Working Memory

工作记忆

Active context during current session; cleared when appropriate.

当前会话的活跃上下文；在合适时机自动清除。

Creating Custom Skills

创建自定义技能

Skill Structure

技能结构

.agent/skills/my-custom-skill/
├── SKILL.md              # Main skill definition
├── README.md             # Documentation
└── tools/                # Optional tool scripts
    └── helper.py

.agent/skills/my-custom-skill/
├── SKILL.md              # 主要技能定义
├── README.md             # 文档说明
└── tools/                # 可选工具脚本
    └── helper.py

SKILL.md Format

SKILL.md格式

markdown

---
name: my-custom-skill
description: Does something specific for this project
version: 1.0.0
triggers:
  - use my custom skill
  - apply custom workflow
---

markdown

---
name: my-custom-skill
description: 为该项目实现特定功能
version: 1.0.0
triggers:
  - use my custom skill
  - apply custom workflow
---

My Custom Skill

我的自定义技能

What It Does

功能说明

Detailed explanation...

详细解释...

When to Use

使用场景

Trigger condition 1
Trigger condition 2

触发条件1
触发条件2

Examples

示例

```python

Working code example

可运行代码示例

```

undefined

```

undefined

Sync Manifest After Adding Skills

添加技能后同步清单

bash

agentic-stack sync-manifest

bash

agentic-stack sync-manifest

Multi-Adapter Setup

多适配器设置

Install Multiple Harnesses

安装多个工具

bash

undefined

bash

undefined

Interactive multi-select

交互式多选

cd your-project ./install.sh

Or add individually

或单独添加

agentic-stack add claude-code agentic-stack add cursor agentic-stack add windsurf

undefined

agentic-stack add claude-code agentic-stack add cursor agentic-stack add windsurf

undefined

Check Installed Adapters

检查已安装适配器

bash

agentic-stack status

Output:

✓ claude-code (active)
✓ cursor (active)
✗ windsurf (not installed)

bash

agentic-stack status

输出示例：

✓ claude-code (已激活)
✓ cursor (已激活)
✗ windsurf (未安装)

Manage via TUI

通过TUI管理

bash

agentic-stack manage

bash

agentic-stack manage

Data Layer Usage

数据层使用

Generate Dashboard

生成仪表盘

python

undefined

python

undefined

From within agent session, trigger:

在Agent会话中触发：

"show me the harness dashboard"

"generate daily report"

Or manually:

或手动执行：

from pathlib import Path import sys sys.path.insert(0, str(Path.cwd() / ".agent" / "skills" / "data-layer")) from dashboard import generate_dashboard

generate_dashboard()

undefined

from pathlib import Path import sys sys.path.insert(0, str(Path.cwd() / ".agent" / "skills" / "data-layer")) from dashboard import generate_dashboard

generate_dashboard()

undefined

View Dashboard

查看仪表盘

bash

open .agent/data/dashboard.html
cat .agent/data/daily-report.md

bash

open .agent/data/dashboard.html
cat .agent/data/daily-report.md

Data Flywheel Usage

数据飞轮使用

Export Approved Runs

导出已批准的运行记录

python

from pathlib import Path
import sys
sys.path.insert(0, str(Path.cwd() / ".agent" / "skills" / "data-flywheel"))
from export import export_run

python

from pathlib import Path
import sys
sys.path.insert(0, str(Path.cwd() / ".agent" / "skills" / "data-flywheel"))
from export import export_run

Export specific run

导出特定运行记录

export_run( run_id="2026-05-16-auth-refactor", redact_secrets=True, include_context=True )

undefined

export_run( run_id="2026-05-16-auth-refactor", redact_secrets=True, include_context=True )

undefined

Artifacts Generated

生成的工件

```
traces/
```
- Execution traces
```
context-cards/
```
- Contextual summaries
```
eval-cases/
```
- Test cases for evaluation
```
training.jsonl
```
- Training-ready format
```
metrics.json
```
- Flywheel readiness metrics

```
traces/
```
- 执行追踪记录
```
context-cards/
```
- 上下文摘要
```
eval-cases/
```
- 评估用测试用例
```
training.jsonl
```
- 可用于训练的格式
```
metrics.json
```
- 数据飞轮就绪指标

Brain Integration

Brain集成

Bridge from Agent Code

从Agent代码桥接

python

#!/usr/bin/env python3
from pathlib import Path
import sys
sys.path.insert(0, str(Path.cwd() / ".agent" / "tools"))
from brain_bridge import query_brain, write_brain

python

#!/usr/bin/env python3
from pathlib import Path
import sys
sys.path.insert(0, str(Path.cwd() / ".agent" / "tools"))
from brain_bridge import query_brain, write_brain

Query across projects

跨项目查询

results = query_brain("authentication patterns") for hit in results: print(f"{hit['project']}: {hit['content']}")

Write durable note

写入持久化笔记

write_brain( content="OAuth refresh tokens expire after 30 days", tags=["auth", "security"] )

undefined

write_brain( content="OAuth refresh tokens expire after 30 days", tags=["auth", "security"] )

undefined

MCP Integration

MCP集成

bash

undefined

bash

undefined

Get MCP stdio command for harness config

获取用于工具配置的MCP标准输入输出命令

agentic-stack brain mcp-command


Add to `.claude/mcp.json` or equivalent:

```json
{
  "mcpServers": {
    "brain": {
      "command": "brain",
      "args": ["serve"]
    }
  }
}

agentic-stack brain mcp-command


添加到`.claude/mcp.json`或等效文件：

```json
{
  "mcpServers": {
    "brain": {
      "command": "brain",
      "args": ["serve"]
    }
  }
}

Troubleshooting

故障排除

Doctor Reports Issues

Doctor报告问题

bash

agentic-stack doctor

Common issues:

Missing hooks: Re-run
```
agentic-stack add <adapter>
```
Orphaned files: Use
```
agentic-stack remove <adapter>
```
then reinstall
Version drift: Run
```
agentic-stack upgrade --yes
```

bash

agentic-stack doctor

常见问题：

缺少钩子：重新运行
```
agentic-stack add <adapter>
```
孤立文件：使用
```
agentic-stack remove <adapter>
```
然后重新安装
版本偏移：运行
```
agentic-stack upgrade --yes
```

Manifest Out of Sync

清单不同步

bash

undefined

bash

undefined

Rebuild from installed SKILL.md files

从已安装的SKILL.md文件重建

agentic-stack sync-manifest

undefined

agentic-stack sync-manifest

undefined

Python 3.9 Compatibility

Python 3.9兼容性

Ensure Python 3.9+ is available:

bash

python3 --version

If using brew Python:

bash

brew install python@3.11

确保Python 3.9+可用：

bash

python3 --version

如果使用brew安装的Python：

bash

brew install python@3.11

Migration from Pre-v0.9

从v0.9之前版本迁移

bash

undefined

bash

undefined

Synthesize install.json from on-disk adapters

从磁盘上的适配器合成install.json

./install.sh doctor

undefined

./install.sh doctor

undefined

Brain Not Found

找不到Brain

bash

undefined

bash

undefined

Install Brain CLI first

先安装Brain CLI

brew install codejunkie99/tap/brain

Verify installation

验证安装

brain --version

undefined

brain --version

undefined

Adapter Conflicts

适配器冲突

bash

undefined

bash

undefined

Remove conflicting adapter

移除冲突的适配器

agentic-stack remove cursor

Clean reinstall

清理后重新安装

agentic-stack add cursor

undefined

agentic-stack add cursor

undefined

Environment Variables

环境变量

Common environment variables referenced:

bash

undefined

常用环境变量：

bash

undefined

Optional: Custom Brain path

可选：自定义Brain路径

export BRAIN_PATH="$HOME/.config/brain"

Optional: Override .agent directory

可选：覆盖.agent目录

export AGENTIC_STACK_DIR=".agent"

undefined

export AGENTIC_STACK_DIR=".agent"

undefined

Common Patterns

常见模式

Single Harness Setup

单工具设置

bash

cd my-project
agentic-stack claude-code

bash

cd my-project
agentic-stack claude-code

Work exclusively in Claude Code

仅在Claude Code中工作

undefined

undefined

Multi-Harness Setup

多工具设置

bash

cd my-project
agentic-stack add claude-code
agentic-stack add cursor
agentic-stack add windsurf

bash

cd my-project
agentic-stack add claude-code
agentic-stack add cursor
agentic-stack add windsurf

Switch between tools without losing context

切换工具时不丢失上下文

undefined

undefined

CI/Automation

CI/自动化

bash

undefined

bash

undefined

Scripted install (no interactive prompts)

脚本化安装（无交互式提示）

agentic-stack claude-code --yes

Verify installation

验证安装

agentic-stack doctor || exit 1

undefined

agentic-stack doctor || exit 1

undefined

Project Migration

项目迁移

bash

undefined

bash

undefined

Export from old project

从旧项目导出

cd old-project agentic-stack transfer

Follow export prompts, save curl command

按照导出提示操作，保存curl命令

Import to new project

导入到新项目

cd new-project

Paste and run curl command

粘贴并运行curl命令

undefined

undefined

Skill Development Workflow

技能开发工作流

bash

undefined

bash

undefined

1. Create skill directory

1. 创建技能目录

mkdir -p .agent/skills/my-skill

2. Write SKILL.md with frontmatter

2. 编写带前置元数据的SKILL.md

cat > .agent/skills/my-skill/SKILL.md << 'EOF'

name: my-skill description: Custom skill for X version: 1.0.0 triggers: ["use my skill"]

cat > .agent/skills/my-skill/SKILL.md << 'EOF'

name: my-skill description: 为X场景定制的技能 version: 1.0.0 triggers: ["use my skill"]

My Skill

我的技能

... EOF

3. Sync manifest

3. 同步清单

agentic-stack sync-manifest

4. Verify

4. 验证

grep "my-skill" .agent/skills/_manifest.jsonl

undefined

grep "my-skill" .agent/skills/_manifest.jsonl

undefined

Safe Upgrades

安全升级

bash

undefined

bash

undefined

1. Preview changes

1. 预览变更

agentic-stack upgrade --dry-run

2. Review output

2. 查看输出

3. Apply if safe

3. 确认安全后应用

agentic-stack upgrade --yes

4. Verify

4. 验证

agentic-stack doctor

undefined

agentic-stack doctor

undefined

Version History Highlights

版本历史亮点

v0.18.0: External Brain memory integration
v0.17.0: Adapters, Mission Control, lesson retraction
v0.16.0: Safe project upgrades via
```
upgrade
```
command
v0.12.0: tldraw visual canvas (opt-in beta)
v0.11.0: Data layer + data flywheel
v0.10.0: design-md skill, Python 3.9 fix
v0.9.0: Manifest-driven harness manager

v0.18.0：外部Brain记忆集成
v0.17.0：适配器、任务控制、课程撤回功能
v0.16.0：通过
```
upgrade
```
命令实现安全项目升级
v0.12.0：tldraw可视化画布（可选测试版）
v0.11.0：数据层 + 数据飞轮
v0.10.0：design-md技能、Python 3.9修复
v0.9.0：基于清单的工具管理器