duychris/universal-agent-memory

Persistent Working Discipline, Shared Memory & Multi-Agent Handoff Skill for Claude Code, OpenAI Codex, Gemini CLI & Antigravity
-brightgreen.svg)
🌐 Languages: English | Tiếng Việt (README) | Hướng Dẫn Sử Dụng Chi Tiết (VI)
## ⚡ What Is This?
Universal Agent Memory (universal-agent-memory) is a lightweight, zero-dependency Agent Skill + Global Rules anchor distilled from a production multi-agent repository (~1,400 project files and operational records, including 110+ atomic memory cards) where Claude, Codex, and Gemini collaborated daily.
It is NOT a vector database, SaaS wrapper, MCP server, or CLI daemon. It is a pure Markdown behavioral contract that teaches your AI agents how to:
1. Read context leanly before acting (AGENTS.md → memory/MEMORY.md index → only relevant atomic cards).
2. Checkpoint mid-session after verified milestones and before high-risk steps to minimize lost state if a session hits quota limits, compacts context, or interrupts early (note: unrecorded in-flight work before a crash still requires workspace verification on resume).
3. Never destroy each other's Work-In-Progress (WIP) (bans blind git add -A, git checkout --, and unscoped file deletions).
4. Separate "Completed" from "Verified" and "Published"—preventing AI hallucinations of "all tests pass / already deployed."
5. Cross-review independently across different models (Claude ↔ Codex ↔ Gemini) with strict attribution and provenance.
6. Learn selectively from user corrections (feedback-.md) and decisions (decision-.md) with semantic deduplication instead of dumping raw chat logs.
Works across any domain—software engineering, research, data analysis, writing, business operations, creative projects, and personal learning (Git rules only activate when the workspace actually uses Git).
## 🏗️ How the 4-Layer Architecture Works
Why do standard AI skills fail across sessions? Because Skills are loaded on-demand—if you type a short prompt in a new session, the AI often forgets to activate the skill.
v3 solves this with a 4-layer architecture:
text
┌─────────────────────────────────────────────────────────────────────────┐
│ LAYER 1: GLOBAL RULES ANCHOR (Always-On, ~8 lines in CLAUDE.md/AGENTS) │
│ Reminds the agent on every stateful task to load Universal Agent Memory │
└───────────────────────────────────┬─────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ LAYER 2: SKILL.md (4 Adaptive Modes: LIGHT · STANDARD · COLLAB · LEARN) │
│ Enforces verification, Git WIP safety, cross-review & learning gates │
└─────────────────┬───────────────────────────────────┬───────────────────┘
▼ ▼
┌───────────────────────────────────┐ ┌───────────────────────────────────┐
│ LAYER 3: MID-SESSION CHECKPOINT │ │ LAYER 4: CANONICAL MEMORY STORE │
│ handoffs/latest.md │ │ memory/MEMORY.md (1-line index) │
│ Saved right after verified steps │ │ + feedback-.md / decision-.md │
│ & before risky actions │ │ + CHANGELOG.md │
└───────────────────────────────────┘ └───────────────────────────────────┘
## 🚀 Quick Install
> Security Note: Piping any remote script directly from main executes the latest branch contents. For maximum safety, we recommend downloading and inspecting the script first (or pinning the immutable release tag v3.0.0) and running --dry-run to preview changes. Both installers automatically back up existing Global Rules and modified Skill files before updating.