agentic-stack-portable-agent-memory

name	agentic-stack-portable-agent-memory
description	Portable .agent/ folder with memory, skills, and protocols that works across Claude Code, Cursor, Windsurf, and other AI coding harnesses
triggers	["set up agentic stack for this project","install portable agent memory","configure agent harness with agentic stack","switch between cursor and claude code without losing memory","add agentic stack brain to my project","manage multiple AI coding agents in one project","create portable agent skills folder","set up cross-harness agent memory"]

agentic-stack-portable-agent-memory

Skill by ara.so — AI Agent Skills collection.

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

Installation

macOS / Linux

# 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

Windows (PowerShell)

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

Clone Method

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

Upgrade Existing Installation

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

Key Commands

Project Management

# Interactive dashboard
agentic-stack dashboard

# Web-based mission control (beta)
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

Upgrade & Sync

# 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

Brain Integration (Optional)

# Install Brain CLI
brew install codejunkie99/tap/brain

# Check Brain status
agentic-stack brain status

# Onboard project to Brain
agentic-stack brain onboard --agents codex,cursor --yes

# Query Brain memory
agentic-stack brain ask "auth decisions"

# Write to Brain memory
agentic-stack brain note "Use PKCE for local OAuth flows."

# Get MCP command
agentic-stack brain mcp-command

Memory Transfer

# Export/import memory between projects
agentic-stack transfer

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

Configuration

Initial Setup (Onboarding Wizard)

The wizard populates .agent/memory/personal/PREFERENCES.md:

# Accept all defaults (CI mode)
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]

Manual Preference Editing

Edit .agent/memory/personal/PREFERENCES.md directly:

---
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.

Feature Toggles

Edit .agent/memory/.features.json:

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

Working with Memory Layers

Personal Memory

# 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

Semantic Memory

# .agent/memory/semantic/architecture_decisions.md
"""
Document lasting project knowledge
"""

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

SKILL.md Format

---
name: my-custom-skill
description: Does something specific for this project
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

## Examples

\```python
# Working code example
\```

Sync Manifest After Adding Skills

agentic-stack sync-manifest

Multi-Adapter Setup

Install Multiple Harnesses

# Interactive multi-select
cd your-project
./install.sh

# Or add individually
agentic-stack add claude-code
agentic-stack add cursor
agentic-stack add windsurf

Check Installed Adapters

agentic-stack status

Output:

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

Manage via TUI

agentic-stack manage

Data Layer Usage

Generate Dashboard

# From within agent session, trigger:
# "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()

View Dashboard

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

Data Flywheel Usage

Export Approved Runs

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
)

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

Brain Integration

Bridge from Agent Code

#!/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"]
)

MCP Integration

# Get MCP stdio command for harness config
agentic-stack brain mcp-command

Add to .claude/mcp.json or equivalent:

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

Troubleshooting

Doctor Reports Issues

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

Manifest Out of Sync

# Rebuild from installed SKILL.md files
agentic-stack sync-manifest

Python 3.9 Compatibility

Ensure Python 3.9+ is available:

python3 --version

If using brew Python:

brew install python@3.11

Migration from Pre-v0.9

# Synthesize install.json from on-disk adapters
./install.sh doctor

Brain Not Found

# Install Brain CLI first
brew install codejunkie99/tap/brain

# Verify installation
brain --version

Adapter Conflicts

# Remove conflicting adapter
agentic-stack remove cursor

# Clean reinstall
agentic-stack add cursor

Environment Variables

Common environment variables referenced:

# Optional: Custom Brain path
export BRAIN_PATH="$HOME/.config/brain"

# Optional: Override .agent directory
export AGENTIC_STACK_DIR=".agent"

Common Patterns

Single Harness Setup

cd my-project
agentic-stack claude-code
# Work exclusively in Claude Code

Multi-Harness Setup

cd my-project
agentic-stack add claude-code
agentic-stack add cursor
agentic-stack add windsurf
# Switch between tools without losing context

CI/Automation

# Scripted install (no interactive prompts)
agentic-stack claude-code --yes

# Verify installation
agentic-stack doctor || exit 1

Project Migration

# Export from old project
cd old-project
agentic-stack transfer
# Follow export prompts, save curl command

# Import to new project
cd new-project
# Paste and run curl command

Skill Development Workflow

# 1. Create skill directory
mkdir -p .agent/skills/my-skill

# 2. Write SKILL.md with frontmatter
cat > .agent/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Custom skill for X
version: 1.0.0
triggers: ["use my skill"]
---
# My Skill
...
EOF

# 3. Sync manifest
agentic-stack sync-manifest

# 4. Verify
grep "my-skill" .agent/skills/_manifest.jsonl

Safe Upgrades

# 1. Preview changes
agentic-stack upgrade --dry-run

# 2. Review output
# 3. Apply if safe
agentic-stack upgrade --yes

# 4. Verify
agentic-stack doctor

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