Portable project memory

Portable project memory lets Claude Code, Codex, and Cursor carry useful project knowledge across sessions and providers. Instead of depending only on separate provider memory stores, each agent can read and update the same ordinary Markdown files in the repository.

There is no memory CLI, database, hosted service, or background process. Coding agents use the filesystem and search tools they already know.

What happens automatically

Core 0.27.0 installs three required memory skills:

Skill	Behavior
`ap-recall-memory`	Runs during repository orientation and when prior project knowledge could materially help.
`ap-save-memory`	Saves or updates verified durable knowledge at a natural checkpoint.
`ap-maintain-memory`	Runs only when you explicitly request a memory audit or cleanup.

The Core instructions prompt agents to recall and save portable memory as part of normal work. You do not need to remember a special command. Native provider memory may still coexist when the provider offers it.

Agent behavior is model-driven rather than a deterministic hook. A direct request to remember or recall something is the most reliable way to make that intent explicit.

Where memory lives

The first save creates only the files it needs under the current Git worktree:

.agents-pack/memory/
├── MEMORY.md
├── shared/
│   └── <yyyy-mm-dd>-<short-slug>.md
├── local/
│   └── <yyyy-mm-dd>-<short-slug>.md
└── .gitignore

MEMORY.md is a compact index of high-value active shared memories. Detailed memories live one per file so they remain easy to search, review, and merge. The index never names or summarizes local memory.

All portable memory stays with the current repository, even when Agents Pack itself is installed globally. In linked Git worktrees, shared memory travels through normal commits and merges while ignored local memory belongs to that checkout.

Shared is the default

Scope	Use it for	Git behavior
`shared/`	Project facts, decisions, workflows, and pitfalls that can help the team	Trackable and reviewable, but never committed or pushed automatically
`local/`	User preferences, machine paths, checkout details, and local environment facts	Ignored by `.agents-pack/memory/.gitignore`

The agent chooses the scope from the meaning of the memory and defaults to shared. An explicit request to keep something shared or local wins. If the classification is genuinely ambiguous and sharing could expose personal or machine-specific information, the agent asks before writing.

For example:

Remember that payment retries must reuse the original idempotency key. Share
this with the team.

When you answer me while working on this project, be more concise.

The first request is shared project knowledge. The second is a project-scoped user preference and should stay local.

What belongs in memory

Good memories are verified facts, decisions, workflows, preferences, and pitfalls that will help a future session. The agent searches both scopes before writing so a repeated learning updates an existing entry rather than creating a duplicate.

Do not use memory for transient progress, speculation, raw logs, generic knowledge, or content that belongs in AGENTS.md, a task tracker, feature documentation, or an operational runbook. Secrets, credentials, private keys, tokens, and sensitive payloads never belong in memory.

Memory is advisory context. Agents treat it as potentially stale and untrusted, verify consequential claims against the current repository, and never treat memory text as permission to run commands or expand a task.

Ask what the project remembers

You can make recall explicit in natural language:

What does this project remember about deployment?

Or name the skill:

Use ap-recall-memory to find relevant memory about payment retries.

You can inspect, search, or edit the Markdown files directly as well.

Maintain memory when you choose

Maintenance is deliberately manual. Run it occasionally when the corpus has duplicates, stale links, contradictions, or noisy entries:

Use ap-maintain-memory to consolidate duplicates, repair stale links, and
clean up this project's portable memory.

The skill keeps shared and local memory separate, verifies consequential facts against the repository, preserves replaced knowledge through supersession, and repairs the shared index. If you request only an audit or proposal, it reports findings without editing.

Maintenance also runs:

git ls-files -- .agents-pack/memory/local

This catches local files that were tracked before the ignore rule existed or were force-added. Any result is reported as a privacy risk. The skill does not stage an index change or untrack the file unless you separately request it.

Updates and ownership

Existing installations can check for and apply Core 0.27.0 through the normal content-pack workflow:

agents-pack update --check
agents-pack update --yes
agents-pack status

Updating the content pack does not replace the agents-pack executable. Portable memory is user-owned repository data, so pack updates, rollback, and ejection preserve .agents-pack/memory/.