# Implementation patterns

> Optional features for safer and more capable memory systems.


None of these features are required for Agent Memory compatibility. Add the ones that fit your harness.

## Git history

Tracking the memory directory with git makes edits inspectable and reversible. A harness may commit after memory writes, identify whether the author was the agent or a person, and synchronize through any git remote.

Git tracking does not imply a public repository. Memory often contains personal or organizational context and should use an appropriately private remote when it leaves the machine.

## Core-memory budget

Because every root Markdown file is loaded, measure their combined token count before prompt compilation or before accepting a write. Warn or refuse when core memory exceeds the harness’s configured budget.

A reasonable default is at most 15 percent of the model’s context window. The limit should be configurable because models and harnesses have different context budgets.

When rejecting a write, tell the agent to move detail into a subdirectory and update the relevant `MEMORY.md` files.

## Index maintenance

Every memory directory requires `MEMORY.md`, but harnesses may maintain those files in different ways:

- **Agent-authored:** the agent writes directory context and retrieval guidance based on what it has learned.
- **Generated:** the harness writes an immediate-child listing or directory summary.
- **Mixed:** the harness maintains a generated section while the agent maintains descriptions and guidance.

When files move or disappear, check index references and surface stale entries. A harness may also show immediate child directories separately from the on-disk index.

## Refresh behavior

Core memory may be compiled once per session, refreshed on the next turn, or rebuilt after a write or commit. Each approach is compatible.

Document when changes become visible. Immediate recompilation keeps context current but may reduce prompt-cache reuse; session or commit boundaries are simpler and more cache-friendly.

## Storage and synchronization

The memory root may be a local directory, a git checkout, an object-store projection, or a database-backed filesystem. Remote and sandboxed agents only need the same directory view where prompt compilation and external-memory reads happen.

When several writers share memory, the storage layer is responsible for synchronization and conflicts. Agent Memory does not define that protocol.

## Writes and permissions

Read-only Agent Memory is valid. A harness may also expose writable files, writable subdirectories, or attached sources with different owners.

Keep credentials and tokens outside memory. If the harness lets agents write, apply the same permission, audit, and secret-scanning rules used for other files.