# agentMemory
> Language: **English** | [中文](README_cn.md)
`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:
```powershell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.ps1))) -Tool claude
```
Shell on macOS / Linux:
```sh
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:
```powershell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.ps1))) -Tool codex
```
Shell on macOS / Linux:
```sh
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:
```powershell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.ps1))) -Tool opencode
```
Shell on macOS / Linux:
```sh
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:
```powershell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install-skill.ps1))) -Tool gemini
```
Shell on macOS / Linux:
```sh
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:
```powershell
irm https://raw.githubusercontent.com/taichuy/agentMemory/main/install.ps1 | iex
```
Shell on macOS / Linux:
```sh
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:
```markdown
# 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
```text
.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](https://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](LICENSE).
---
## Contributors
<p align="center">
<a href="https://github.com/taichuy/agentMemory/graphs/contributors">
<img src="https://contrib.rocks/image?repo=taichuy/agentMemory&max=50" alt="Contributors" />
</a>
</p>
## Star History
<p align="center">
<a href="https://www.star-history.com/#iOfficeAI/aionui&Date" target="_blank">
<img src="https://api.star-history.com/svg?repos=taichuy/agentMemory&type=Date" alt="Star History" width="600">
</a>
</p>
<div align="center">
**If you like it, give us a star**
[Report Bug](https://github.com/taichuy/agentMemory/issues) · [Request Feature](https://github.com/taichuy/agentMemory/issues)
</div>