ShareMemory

English | 中文

Your agents forget everything between sessions - and they have never met each other.

Project-scoped shared memory for AI coding agents, packaged as a single skill that works in both Claude Code and Codex.

One AI_MEMORY/ folder turns isolated Claude Code and Codex sessions into a shared, linted project handoff loop.

See it run · Install · Use it daily · Design details · Maintainer catch-up · Verify it · Safety

---

Claude Code and Codex do not share context. When both agents work in the same repository, each is blind to the other's decisions, and every new session starts from zero. ShareMemory solves this with a file-based single source of truth (AI_MEMORY/) inside each project: both agents are bound by the same protocol to read it on startup and write to it as they work — so each agent always sees what the other one did.

See It in Action

30-Second Quick Start

Recommended for a target project: install one repo-local copy for Codex, then expose the same copy to Claude Code.

# Run inside the repo where you want both agents to use ShareMemory
npx skills add ycl-2004/ShareMemory --skill share-memory --agent codex --copy --yes
mkdir -p .claude/skills
ln -sfn ../../.agents/skills/share-memory .claude/skills/share-memory

Codex reads repo skills from .agents/skills/. Claude Code reads project skills from .claude/skills/. The symlink keeps both agents on the same ShareMemory code in that repo.

Warning

Don't run the install command inside the ShareMemory source repo itself. --copy installs a copy of the skill into the current folder, so running it here would nest a copy of ShareMemory inside its own source tree. Run it in the project where you actually want shared memory.

Or install manually without Node.js:

mkdir -p .agents/skills .claude/skills
git clone https://github.com/ycl-2004/ShareMemory .agents/skills/share-memory
ln -sfn ../../.agents/skills/share-memory .claude/skills/share-memory

Then open that repo in Claude Code or Codex and say init memory. Open the same folder with the other agent and it will read the same AI_MEMORY/ state instead of starting from zero.

Verify it worked — after init memory, paste this into either agent:

memory status

Expected: a status report showing protocol version, language, git setting, and the init log entry.

MIT licensed. No runtime dependencies. One shared memory per repo.

What You Get

• One project-local AI_MEMORY/ folder shared by Claude Code and Codex.
• A small protocol for startup reads, daily handoffs, decisions, tasks, learnings, and corrections.
• A write lock plus scripts/check_memory.sh so memory stays small, signed, and linted.
• Optional git recovery for AI_MEMORY/ history.

Install

Codex + Claude Code

npx skills add ycl-2004/ShareMemory --skill share-memory --agent codex --copy --yes
mkdir -p .claude/skills
ln -sfn ../../.agents/skills/share-memory .claude/skills/share-memory

Run this from the repo that should use shared memory. Codex reads .agents/skills/share-memory; Claude Code reads the symlinked .claude/skills/share-memory. Both use one project-local skill copy.

Codex only

npx skills add ycl-2004/ShareMemory --skill share-memory --agent codex --copy --yes

.agents/skills/share-memory/SKILL.md

Claude Code only

npx skills add ycl-2004/ShareMemory --skill share-memory --agent claude-code --copy --yes

.claude/skills/share-memory/SKILL.md

Manual, no Node.js

Shared copy:

mkdir -p .agents/skills .claude/skills
git clone https://github.com/ycl-2004/ShareMemory .agents/skills/share-memory
ln -sfn ../../.agents/skills/share-memory .claude/skills/share-memory

Optional personal global install

Use this on your own machine when you want init memory available in any project. The skill is global; each project's AI_MEMORY/ is still separate.

mkdir -p ~/.claude/skills ~/.agents/skills
git clone https://github.com/ycl-2004/ShareMemory ~/.agents/skills/share-memory
ln -sfn ~/.agents/skills/share-memory ~/.claude/skills/share-memory

Update it with:

git -C ~/.agents/skills/share-memory pull --ff-only

Updating ShareMemory

The update path depends on how the skill was installed.

If you installed with npx skills add --copy

--copy creates a project-local copy of the skill, not a git checkout. To update it, rerun the same install command from the target repo. The Claude symlink can stay in place.

Codex + Claude Code shared copy:

npx skills add ycl-2004/ShareMemory --skill share-memory --agent codex --copy --yes
mkdir -p .claude/skills
ln -sfn ../../.agents/skills/share-memory .claude/skills/share-memory

Codex only:

npx skills add ycl-2004/ShareMemory --skill share-memory --agent codex --copy --yes

Claude Code only:

npx skills add ycl-2004/ShareMemory --skill share-memory --agent claude-code --copy --yes

After updating, ask either agent:

memory status

It should report the project's protocol version and recent handoff state. If the installed skill is newer than the project boot layer, it should report the mismatch and offer migrate memory; it must not migrate silently.

If you installed with git clone

Pull the cloned skill directory. For the recommended shared install, only the canonical Codex copy needs a pull:

git -C .agents/skills/share-memory pull --ff-only

If you cloned separate Codex and Claude Code copies, update both:

git -C .agents/skills/share-memory pull --ff-only
git -C .claude/skills/share-memory pull --ff-only

Daily Usage

Most sessions need no memory command: the compact boot layer reads the current handoff, and meaningful decisions or completion state are recorded automatically. Use memory status when you want an explicit report and update memory for routine manual cleanup. The full protocol is loaded by section only when a write or maintenance operation needs it.

Command	Use it when
init memory	First time in a project. Creates protocol files, boot files, lint script, and empty AI_MEMORY/.
memory status	See current project state and what the other agent changed recently.
update memory / sync memory	Manually curate routine task progress or lessons; handoff-critical state is automatic.
consolidate memory	Compress stale or duplicated memory while keeping startup cost stable.
repair memory	Fix drift: missing @AGENTS.md import, duplicate/broken marker blocks, missing files.
migrate memory	Upgrade an older project protocol after explicit approval.

These phrases trigger the skill implicitly on both platforms. In Codex you can also invoke it explicitly by typing $share-memory (or by finding share-memory via /skills, depending on the client). Claude Code picks it up automatically from the skill description. AI_MEMORY/ is only the per-project data folder created by init; the skill id is share-memory.

During init, the skill asks two questions: memory language (中文 / English / bilingual) and whether to enable the git recovery layer. Existing CLAUDE.md / AGENTS.md files are never replaced wholesale — ShareMemory only inserts or refreshes a bounded <!-- SHAREMEMORY:START/END --> marker block and creates a backup first. CLAUDE.md follows Anthropic's recommended pattern: one @AGENTS.md import plus Claude-specific notes, so the shared rules exist in exactly one place.

What init adds to your project

File	Purpose	Written
MEMORY_PROTOCOL.md	The shared rule set both agents follow	init; refreshed by repair/migrate
AGENTS.md	Shared agent-neutral boot rules (Codex reads natively; Claude imports it)	managed marker block
CLAUDE.md	@AGENTS.md import + Claude-only notes (incl. auto-memory policy)	managed marker block
scripts/check_memory.sh	Post-write lint + secrets scan	init; refreshed by repair/migrate
scripts/memory_lock.sh	Owner-checked write lock with stale-lock recovery	init; refreshed by repair/migrate
AI_MEMORY/CONFIG.md	Language, git choice, protocol version	init/migrate
AI_MEMORY/PROJECT.md	Overview, architecture, Long-Term Memory (distilled current state)	auto, on structural change
AI_MEMORY/DECISIONS.md	Decisions and dependency changes (max 5)	auto
AI_MEMORY/TASKS.md	Active and recently completed tasks	auto for handoff-critical state; manual cleanup
AI_MEMORY/LEARNINGS.md	Lessons worth keeping (max 5)	auto for confirmed reusable lessons; manual curation
AI_MEMORY/SYNC_LOG.md	Daily handoff blocks — how the agents see each other without noisy per-write logs	every write session
AI_MEMORY/archive/	Overflowed entries and old logs	on overflow

Durable entries are signed [YYYY-MM-DD HH:MM] [Claude|Codex] with real system time. SYNC_LOG.md keeps at most one compact block per date.

What Gets Written Automatically

• Decisions, dependency/tooling changes, install or publishing contracts → DECISIONS.md.
• Project direction, architecture, workflow, or startup summary changes → PROJECT.md.
• Handoff-critical task state → TASKS.md.
• Confirmed reusable lessons or validation traps → LEARNINGS.md.
• Completed work → today's SYNC_LOG.md block.

If it would not change what the next agent does, it should not become durable memory.

Verification

Check	What it proves
bash assets/demo.sh	Demo project initializes and passes memory lint
bash scripts/check_memory.sh (inside an initialized target project)	That project's memory is valid
CI	Template/boot contract, protocol-version failures, lock ownership, secrets, and demo replay

Verify a source checkout using tracked files:

bash assets/demo.sh
bash -n templates/project/scripts/check_memory.sh
bash -n templates/project/scripts/memory_lock.sh
git diff --check

This repository's richer scripts/test_memory_templates.sh and dogfood scripts/check_memory.sh are local maintainer files intentionally excluded from the published package. In any initialized target project, bash scripts/check_memory.sh is available normally.

Conflict & Safety Rules

• User instruction wins; agents must point out conflicts with memory instead of silently overriding either side.
• Read-only instructions pause all automatic AI_MEMORY/ writes.
• Memory is not a diary: no raw reasoning, chat dumps, verbose logs, secrets, tokens, or private URLs.
• Do not run both agents on the same project at the same time; the write lock prevents accidental overlap, not live collaboration.
• Publishing a public repo? Treat AI_MEMORY/ as internal project context unless you intentionally want it public.

Requirements

No runtime package installation. The skill is plain Markdown plus two bash helper scripts; init only copies template files.

Dependency	Needed for	If missing
bash + coreutils (grep, awk, wc, date, sort, uniq)	lint script, timestamps	Preinstalled on macOS/Linux; Windows via WSL or Git Bash
git (optional)	recovery layer for AI_MEMORY/ history	Everything still works; you lose overwrite recovery
Node.js / npx (optional)	npx skills add installation path	Use the documented git clone install instead

The skill never auto-installs software. During init it asks whether to enable git, records the choice in CONFIG.md, and only ever runs git init with explicit permission.

Design Details

The full design analysis — what it does, capability boundaries, short-term vs long-term use, pros/cons, and the complete risk list — lives in PROJECT_DETAILS.md. Chinese version: 项目详解.md.

Chinese README

中文说明、安装路径和日常用法见 README.zh.md。

Contributing

Issues and pull requests are welcome, especially for additional agent boot files, migration helpers, and stronger validation.

License

MIT © 2026 yc星辰

---

Built for projects where more than one AI agent needs the same memory.