universal-memory

Cross-tool project memory and agent handoff for OpenCode, Gemini CLI, Claude Code, Codex, and any agent that can read Markdown files.

Published repository target: https://github.com/txzh007/universal-memory-skill

Two modes

This skill supports two modes:

Mode 1: Manual / zero-dependency (Recommended for most users)

No Node.js required. Just copy the templates and fill them in.

1. Copy these files from templates/ to your project root:

   # From your project root (NOT this repo)
   cp path/to/universal-memory-skill/templates/AGENTS.template.md ./AGENTS.md
   cp path/to/universal-memory-skill/templates/current-work.template.md .agent-context/current-work.md
   cp path/to/universal-memory-skill/templates/next-steps.template.md .agent-context/next-steps.md
   cp path/to/universal-memory-skill/templates/handoff-message.template.md .agent-context/handoff-message.md

2. Create tool-specific memory files:

   cp AGENTS.md agent.md
   cp AGENTS.md GEMINI.md
   cp AGENTS.md CLAUDE.md

3. Before handing off, update .agent-context/current-work.md and .agent-context/next-steps.md.

4. The next agent reads:

   • AGENTS.md
   • .agent-context/current-work.md
   • .agent-context/next-steps.md

Mode 2: Automated / Node-powered

Requires Node.js 14+. Provides automatic file detection and structured handoff.

# From your project root (NOT this repo)
node path/to/universal-memory-skill/init-universal-memory.js
node path/to/universal-memory-skill/capture-state.js --task "Implementing feature X" --next-steps "Step 1, Step 2"
node path/to/universal-memory-skill/handoff.js --to gemini --task "Feature X" --next-steps "Step 1, Step 2"
node path/to/universal-memory-skill/restore-state.js

Tip: Add the skill directory to your PATH or create a wrapper script to avoid typing the full path every time.

What it does

This skill creates a simple, portable memory model for AI-assisted development:

• AGENTS.md as the universal project-memory source
• .agent-context/current-work.md for current session state
• .agent-context/next-steps.md for actionable handoff items
• .agent-context/handoff-message.md for tool-to-tool transfer

It is intentionally file-based so it works even when tools do not share session state.

Included files

Templates (Mode 1)

• templates/AGENTS.template.md - Project memory template
• templates/current-work.template.md - Current work state template
• templates/next-steps.template.md - Next steps template
• templates/handoff-message.template.md - Handoff message template

Scripts (Mode 2)

• init-universal-memory.js - Bootstrap the memory files
• capture-state.js - Capture current work state
• handoff.js - Generate a portable handoff package
• restore-state.js - Restore and summarize saved state

Quick start (Mode 1)

1. Copy templates to your project

# In YOUR PROJECT ROOT (not this repo)
cd /path/to/your-project

# Copy AGENTS.md template
cp /path/to/universal-memory-skill/templates/AGENTS.template.md ./AGENTS.md

# Create .agent-context directory
mkdir .agent-context

# Copy state templates
cp /path/to/universal-memory-skill/templates/current-work.template.md .agent-context/current-work.md
cp /path/to/universal-memory-skill/templates/next-steps.template.md .agent-context/next-steps.md
cp /path/to/universal-memory-skill/templates/handoff-message.template.md .agent-context/handoff-message.md

# Create tool-specific memory files
cp AGENTS.md agent.md
cp AGENTS.md GEMINI.md
cp AGENTS.md CLAUDE.md

2. Customize AGENTS.md

Edit AGENTS.md with your project's identity, conventions, and status.

3. Before handing off

Update .agent-context/current-work.md and .agent-context/next-steps.md with:

• What you're working on
• What files you changed
• What the next agent should do

Quick start (Mode 2)

1. Initialize in your project

# In YOUR PROJECT ROOT (not this repo)
cd /path/to/your-project

# Initialize universal memory
node /path/to/universal-memory-skill/init-universal-memory.js

2. Capture current state

node capture-state.js \
  --task "Implement auth middleware" \
  --next-steps "Handle expired token, add integration test" \
  --files "src/auth/middleware.ts, tests/auth.test.ts" \
  --verification "Manual smoke test passed"

3. Generate a handoff package

node handoff.js \
  --to gemini \
  --task "Implement auth middleware" \
  --next-steps "Handle expired token, add integration test" \
  --message "Continue from captured state"

4. Restore in the next session

node restore-state.js

Install / distribute

As a standalone repository

Clone the repo and run the scripts directly:

git clone https://github.com/txzh007/universal-memory-skill.git
cd universal-memory-skill

Then choose your mode:

• Mode 1: Copy templates manually
• Mode 2: Run node init-universal-memory.js

As a skill source

If your skills workflow supports GitHub-backed skills, publish this repository first and then point your skill manager at the repo.

Recommended repository contents:

• SKILL.md
• README.md
• package.json
• templates/
• Node scripts
• LICENSE

GitHub repository setup

Recommended repository description:

Cross-tool project memory and agent handoff for OpenCode, Gemini CLI, Claude Code, and Codex.

Recommended topics:

• ai-agents
• developer-tools
• opencode
• claude-code
• gemini-cli
• codex
• project-memory
• handoff
• markdown

What it does

This skill creates a simple, portable memory model for AI-assisted development:

• AGENTS.md as the universal project-memory source
• .agent-context/current-work.md for current session state
• .agent-context/next-steps.md for actionable handoff items
• .agent-context/handoff-message.md for tool-to-tool transfer

It is intentionally file-based so it works even when tools do not share session state.

Included scripts

• init-universal-memory.js - bootstrap the memory files and templates
• capture-state.js - capture current work state
• handoff.js - capture state and generate a portable handoff package
• restore-state.js - restore and summarize the last saved state

Quick start

1. Initialize in a project

node init-universal-memory.js

2. Capture current state

node capture-state.js \
  --task "Implement auth middleware" \
  --next-steps "Handle expired token, add integration test" \
  --files "src/auth/middleware.ts, tests/auth.test.ts" \
  --verification "Manual smoke test passed"

3. Generate a handoff package

node handoff.js \
  --to gemini \
  --task "Implement auth middleware" \
  --next-steps "Handle expired token, add integration test" \
  --message "Continue from captured state"

4. Restore in the next session

node restore-state.js

Typical workflow

During active work

node capture-state.js \
  --task "Implement payment retry logic" \
  --next-steps "Handle timeout path, add regression test" \
  --files "src/payments/retry.ts, tests/payments/retry.test.ts" \
  --verification "Timeout case reproduced locally"

Before handing work to another tool

node handoff.js \
  --to claude \
  --task "Implement payment retry logic" \
  --next-steps "Handle timeout path, add regression test" \
  --message "Continue from captured context and preserve existing patterns"

At the start of the next session

node restore-state.js

Capture behavior

capture-state.js detects modified files in this order:

1. explicit --files
2. git working tree changes
3. recent file modification scan fallback

This makes the skill useful both in git repositories and ad-hoc local directories.

Generated files

AGENTS.md
agent.md
GEMINI.md
CLAUDE.md
.agent-context/current-work.md
.agent-context/next-steps.md
.agent-context/handoff-message.md
.sisyphus/universal-memory/handoff-protocol.md
.sisyphus/universal-memory/state-capture-templates/*

Design goals

• file-based and portable
• tool-agnostic
• human-readable
• safe to inspect and edit manually
• useful with or without git

Known limitations

• does not automatically infer the semantic meaning of every changed file
• recent-file fallback may include unrelated files if many files changed recently
• tool-specific memory ingestion still depends on each tool reading the expected filename

Release checklist

Before tagging a release:

• verify README.md, SKILL.md, and package.json all describe the same workflow
• confirm repository URLs and issue tracker links are correct
• run node init-universal-memory.js in a scratch directory
• run node capture-state.js, node handoff.js, and node restore-state.js
• check that generated files are human-readable and paths are correct on your platform
• review commit history for a clean first impression

Recommended publishing structure

If publishing this skill separately, include:

• SKILL.md
• README.md
• package.json
• the four Node scripts
• optional LICENSE

License

MIT