agentMemory

Language: English | 中文

agentMemory is a general-purpose memory template repository for AI-assisted development.

It is not an application codebase. Instead, it provides a practical, versionable .memory/ directory convention for project work. The goal is to manage user preferences, project-stage facts, tool failure notes, reference entry points, and pending confirmations in one stable structure, so an Agent can reuse context across long-running collaboration instead of starting from zero every time.

By default, this repository keeps only rule files and templates. It does not include concrete project examples, which helps prevent old project cases from being accidentally treated as reusable memory when a new project is initialized.

Note: The .memory template files are written in Chinese because practical use has shown that Chinese context is shorter and carries higher information density for this project. If you need another language, ask your AI assistant to translate the templates as needed.

Recommended: install /skills on demand

If you do not want to manually paste initialization commands for every new project, install the agent-memory skill into the global directory of the coding Agent you use. After installing it once, run /skills inside a project. The Agent will create .memory/ automatically and add memory entry points to AGENTS.md, CLAUDE.md, and GEMINI.md.

After installation, the Agent first detects your primary working language, then asks whether to initialize .memory/user-memory.md. Only after confirmation will it ask a small set of project-specific initialization questions.

Installation is explicit and on demand: only the tools you specify are installed. The script will not write Claude Code, Codex, OpenCode, and Gemini entries all at once unless you ask for them.

Claude Code

PowerShell on Windows:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.ps1))) -Tool claude

Shell on macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.sh | sh -s -- --tool claude

Install locations:

• ~/.claude/skills/agent-memory/
• ~/.claude/commands/skills.md

Codex

PowerShell on Windows:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.ps1))) -Tool codex

Shell on macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.sh | sh -s -- --tool codex

Install locations:

• ~/.codex/skills/agent-memory/
• ~/.codex/prompts/skills.md

Trigger with $agent-memory or /prompts:skills.

OpenCode

PowerShell on Windows:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.ps1))) -Tool opencode

Shell on macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.sh | sh -s -- --tool opencode

Install locations:

• ~/.config/opencode/skills/agent-memory/
• ~/.config/opencode/commands/skills.md

Gemini CLI

PowerShell on Windows:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.ps1))) -Tool gemini

Shell on macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.sh | sh -s -- --tool gemini

Install locations:

• ~/.gemini/commands/skills.toml
• ~/.gemini/skills/agent-memory/

For an already open Gemini CLI session, run /commands reload to reload commands.

Update and overwrite

If a skill or command with the same name already exists, the install script keeps the existing file by default to avoid accidental overwrites. To update to the latest version, pass -Update or --update; the script will download again and overwrite the corresponding skill and command files for the selected tool.

• PowerShell update: & ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.ps1))) -Tool codex -Update
• Shell update: curl -fsSL https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.sh | sh -s -- --tool codex --update

-Force / --force is still supported as an alias for -Update / --update.

If you use multiple tools, pass multiple targets explicitly, for example --tool claude,codex. The script will not perform a full installation when no target is specified.

One-command .memory installation

Install the repository's .memory/ directory directly into the current directory:

PowerShell on Windows:

irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install.ps1 | iex

Shell on macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/taichuy/agentMemory/main/install.sh | sh

If .memory/ already exists in the current directory, the script stops by default to avoid accidental overwrite.

• Force overwrite with PowerShell: & ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install.ps1))) -Force
• Force overwrite with Shell: curl -fsSL https://raw.githubusercontent.com/taichuy/agentMemory/main/install.sh | sh -s -- --force

Use cases

During project development, teams often need a dedicated memory directory for information that lives outside the code but still affects decisions over time. agentMemory is useful when you need to:

• Provide stable long-term context to an AI / Agent.
• Turn temporary chat conclusions into reusable project assets.
• Manage user preferences, project consensus, tool failure experience, and reference entry points separately.
• Keep memory content commit-ready, reviewable, portable, and reusable with the repository.

Design reference

This project was inspired by the Claude Code memory system, but moves memory from an in-session capability into a repository-level .memory/ directory, making it a maintainable engineering structure.

The core goals are:

• Make memory a project asset instead of implicit information scattered across context windows.
• Let Agents read summaries first and expand full files only when needed, reducing retrieval noise.
• Give each memory type a clear boundary, avoiding a single mixed pile of context.

Usage

In the repository root, it is recommended to point AGENTS.md, CLAUDE.md, and GEMINI.md to the memory rules explicitly:

# Memory
When content matches the `memory storage rules`, automatically update the corresponding memory.
@.memory/AGENTS.md

## User Preferences
@.memory/user-memory.md

# File Management Convention
1. If a corresponding subdirectory has an AGENTS.md file, read it first before making changes.
2. Every AGENTS.md should provide short, strict, stable local execution rules. Keep it precise, clear, and brief, with a maximum of 200 lines.

Directory structure

.memory/
  AGENTS.md
  user-memory.md
  feedback-memory/
  project-memory/
  reference-memory/
  tool-memory/
  todolist/

Directory responsibilities:

• AGENTS.md: The main memory-system rules, including storage boundaries and retrieval order.
• user-memory.md: Records user role, technical background, work habits, knowledge level, and communication preferences.
• feedback-memory/: Records user corrections or confirmations about collaboration style and engineering practice.
• project-memory/: Records current project-stage facts, short-term consensus, and decision background.
• reference-memory/: Records only entry-point indexes such as "where to look for what"; it does not store conclusions.
• tool-memory/: Records real tool failures and verified solutions.
• todolist/: Records temporary items that need user confirmation during autonomous Agent work. Items should be deleted after being handled and should not become long-term memory.

Memory storage rules

All formal memory files should prefer YAML front matter as the summary layer, with the body used for full context. This supports a workflow of "retrieve the summary first, then expand only when needed."

This template repository also emphasizes one principle: use templates whenever possible instead of asking a model to invent structure. Each memory type should be filled from its corresponding template first, then adapted to the actual project.

1. User memory

User memory records stable information, such as:

• Who the user is.
• The user's technical background and familiar languages.
• The user's work rhythm and communication preferences.
• Long-term preferences for output style, planning, and implementation.

This type of memory should be stable and restrained. It should not become a user profile or emotional journal.

2. Feedback memory

Feedback memory records explicit corrections or confirmations from the user. Each item should include at least:

• What the rule is.
• Why it matters.
• When it applies.

Feedback memory is split into two categories:

• interaction/: Communication, execution flow, memory retrieval, and other interaction feedback.
• repository/: Repository structure, directory management, script placement, version-control practice, and other engineering feedback.

The default decision_policy is direct_reference.

3. Project memory

Project memory records "what is happening now", such as stage goals, short-term consensus, current constraints, who is doing what, and why.

The body of a project memory item should answer at least:

• Who is doing what?
• Why is it being done this way?
• Why does it need to be done?
• What is the deadline?
• What motivated the decision?

This type of memory decays quickly. Its default decision_policy is verify_before_decision, meaning the Agent should verify against current code, documentation, or runtime results before relying on it for a decision.

4. Reference memory

Reference memory only establishes entry-point indexes, such as:

• Where an external source repository is.
• Where API documentation lives.
• Where a script entry point is located.

It does not store conclusions directly. Its default decision_policy is index_only.

5. Tool memory

Tool memory records real tool problems in the project environment and verified solutions. Keep the boundary strict:

• Record only problems that actually happened.
• Record only solutions that have been verified and can be reused.
• Do not write general tool tutorials.
• Do not write speculative future risks.
• If the same tool, problem, and solution reappears, append to the existing file.

The default decision_policy is reference_on_failure.

6. What should not be stored

The following content generally should not be written into .memory/:

• Structure, paths, and implementation details that can be read directly from current code.
• Version information that already exists in git history.
• One-off debugging logs that cannot be reused.
• Content already defined clearly in configuration files.
• Runtime summaries, drafts, and temporary notes unrelated to the memory system.

Memory retrieval rules

This template recommends that Agents retrieve memory in this order:

1. Always read .memory/AGENTS.md first.
2. Always read .memory/user-memory.md second.
3. For feedback-memory, project-memory, reference-memory, and tool-memory, read only the first 30 lines of each file's YAML front matter in the first pass.
4. Scan at most 200 memory files in a single round.
5. Expand at most 5 relevant full memory files in a single round.
6. Prefer precision over volume; expand only genuinely relevant memory, not enough files to fill a quota.
7. Decide whether to use a memory item by considering its type, decision_policy, and relevance, not just its timestamp.
8. If project-memory is more than two days old, verify it against current code, documentation, or runtime results before using it when it still affects the decision.
9. Use reference-memory only as an index entry point, not as a final source of truth.
10. Use tool-memory only when the current task needs that tool or when that tool has just failed.

Why this structure

The point of this structure is not to store more content. It is to put reusable content in the right place.

Benefits include:

• Lower cost for Agents to understand project background each round.
• Separation between long-term preferences and short-term facts, reducing information pollution.
• Reusable tool experience instead of one-off chat history.
• Memory content that can be maintained, reviewed, and inherited like code.

Recommended workflow

If you plan to use this repository as a template for a new project, the recommended flow is:

1. Keep the root .memory/ structure as the memory-system entry point.
2. Initialize user-memory.md and each memory template according to the actual project.
3. During each project collaboration, write genuinely reusable information back into the correct memory category.
4. Let the Agent read .memory according to the retrieval rules before implementation or decision-making.

This repository already provides templates for each memory type:

• user-memory.md: user memory template.
• feedback-memory/template.md, interaction/template.md, repository/template.md: feedback memory templates.
• project-memory/template.md: project memory template.
• reference-memory/template.md, source-reference.md, api-reference.md, script-reference.md: reference memory templates.
• tool-memory/template.md: tool memory template.
• todolist/template.md: pending-confirmation template.

From this perspective, agentMemory is essentially a memory-management template repository for AI-assisted development.

Acknowledgements

Thanks to the Linux.do community for its support. Special thanks to everyone in the L community for sharing learning notes and experience.

---

License

This project is licensed under Apache-2.0.

---

Contributors

Star History

If you like it, give us a star

Report Bug · Request Feature