Agent Memory Tools

Local, installable Markdown memory tools for coding agents.

The package installs one executable:

agent-memory

Source repository:

https://codeberg.org/rch/agent-memory-tools.git

It manages a global memory directory with this shape:

memory/
├── INDEX.md
├── README.md
├── entries/
└── archive/

How Memory Is Preserved

agent-memory-tools preserves agent memory as Markdown files on your local filesystem. The CLI package and memory data are separate, so reinstalling or uninstalling the CLI does not delete the memory directory.

By default, memory is kept here:

~/.local/share/agent-memory-tools/memory

Each memory is written as one Markdown file in entries/, and INDEX.md is regenerated as a compact lookup table for retrieval. Retrieval reads the index first, then opens only the most relevant active entries instead of loading the whole memory store.

Write and cleanup commands use file locking, atomic writes, safety scans, index regeneration, and verification so the memory store stays consistent. Backups are created as .tar.gz archives containing the full memory directory.

More details are in docs/memory-system-spec.md, docs/memory-tooling-and-agent-editing.md, and docs/operations.md.

Install

Clone the repository first:

git clone https://codeberg.org/rch/agent-memory-tools.git
cd agent-memory-tools

Recommended Linux install from the checkout with pipx:

sudo apt install pipx
pipx ensurepath
make install

Restart your shell, or run:

source ~/.profile

Verify:

agent-memory --help

pipx is recommended because many Linux distributions mark system Python as externally managed under PEP 668. Avoid pip --break-system-packages unless you intentionally want to bypass that protection.

To install directly without make:

pipx install .

Alternative venv install:

python3 -m venv ~/.local/share/agent-memory-tools/venv
~/.local/share/agent-memory-tools/venv/bin/pip install .
ln -s ~/.local/share/agent-memory-tools/venv/bin/agent-memory ~/.local/bin/agent-memory

Development install from the cloned checkout:

make install-editable

Install the default role-scoped skills into ~/.agents/skills:

make install-skills

Install the all-agents skillset, where every installed memory skill is available to any agent:

make install-skills SKILL_PROFILE=all-agents

Install skills by agent group:

make install-skills SKILL_GROUP=memory-manager
make install-skills SKILL_GROUP=code-validator

Install selected skills by name:

make install-skills SKILL_NAMES="memory-retrieval memory-verify"

Override the skill target if needed:

make install-skills SKILLS_DIR=/path/to/skills

Update an installed CLI from the same checkout:

git pull
make update

Memory Directory

By default memory is stored at:

~/.local/share/agent-memory-tools/memory

Override it globally:

export AGENT_MEMORY_DIR="$HOME/.agent-memory"

Or per command:

agent-memory --memory-dir /path/to/memory retrieve --query "auth token"

Commands

Show project maintenance commands:

make help

Update the installed CLI from this checkout:

make update

Uninstall the CLI while keeping memory data untouched:

make uninstall

Install or remove the agent-facing skills:

make install-skills
make uninstall-skills
make install-skills SKILL_PROFILE=all-agents
make install-skills SKILL_GROUP=memory-manager
make install-skills SKILL_NAMES="memory-retrieval"
make uninstall-skills SKILL_GROUP=memory-manager
make uninstall-skills SKILL_NAMES="memory-retrieval"

Pass a non-default memory directory to verification or backup targets:

make verify MEMORY_DIR=/path/to/memory
make backup MEMORY_DIR=/path/to/memory

CLI Commands

Initialize memory:

agent-memory init

Retrieve relevant memories:

agent-memory retrieve --query "dashboard auth token" --project dashboard --tags auth,jwt

Create a memory from a structured file:

agent-memory write --input new-memory.yaml

Regenerate the index:

agent-memory index-update

Verify integrity:

agent-memory verify

Cleanup operations:

agent-memory clean --find-duplicates
agent-memory clean --supersede old-auth-token-format --by auth-token-format-v2
agent-memory clean --archive old-auth-token-format --reason "promoted to docs"

Back up memory data before upgrades or large cleanup:

agent-memory backup

Agent Skills

This repository ships OpenCode memory skill profiles under skillsets/. Install them with make install-skills so agents know which memory operations they are allowed to use.

Profiles:

• role-scoped: default profile; write, clean, index, and maintenance skills are limited to memory-manager.
• all-agents: permissive skillset; every installed memory skill is available to any agent.

Install examples:

make install-skills
make install-skills SKILL_PROFILE=all-agents
make install-skills SKILL_GROUP=memory-manager
make install-skills SKILL_NAMES="memory-retrieval memory-verify"

• memory-retrieval: for agents allowed to retrieve compact memory briefs when useful.
• memory-write: for memory-manager to create durable entries through agent-memory write.
• memory-index-update: for memory-manager to regenerate INDEX.md.
• memory-clean: for memory-manager to back up, deduplicate, archive, and supersede memories.
• memory-verify: for memory-manager and code-validator to check store integrity.

The access model comes from docs/memory-tooling-and-agent-editing.md.

Write Input Format

agent-memory write accepts JSON, simple YAML, or a full Markdown memory file with frontmatter.

Example YAML:

id:auth-token-formatproject:backendtags:[auth, jwt, dashboard]importance:0.9title:JWT validation moved to shared middlewaresummary:JWT validation now happens in shared backend middleware, and dashboard depends on token payload shape.decisions:- Do not parse JWT tokens directly inside route handlers.- Use src/middleware/auth.ts for token validation.impact:- Dashboard may break if token payload fields change.related_projects:[backend, dashboard, workers]important_files:- src/middleware/auth.ts- src/auth/jwt.tsretrieve_when:- login- JWT validation- dashboard authentication

Agent Rules

• Coders use retrieve only.
• Memory summarizers use write, index-update, and verify.
• Memory cleaners use clean, index-update, and verify.
• Validators can use retrieve and verify.
• Tools perform file operations; agents make semantic decisions.

Safety

The tools enforce:

• Kebab-case memory ids.
• Required frontmatter and summary.
• importance between 0 and 1.
• Valid status values.
• No duplicate ids.
• Active entries listed in INDEX.md.
• Index rows point to existing files.
• Basic secret, prompt-injection, giant diff, and giant log checks.
• Atomic writes and a lock file around write/cleanup operations.

Docs

• Usage
• Day-2 Operations
• Memory System Specification
• Tooling and Agent Editing Specification