Git as Memory

Git-backed memory policy and CLI workflow for OpenClaw, Hermes, Claude Code, Codex, and other agents. Use when an agent should remember durable user preferences, project decisions, conventions, lessons learned, or query/audit Git-native memory with gam.

Use git-as-memory as a durable, auditable memory layer for agents. It stores memory in a dedicated Git ref, not in the working tree.

Default ref:

refs/git-as-memory/memory/v1

Supported agents: OpenClaw, Hermes, Claude Code, Codex, or any agent that can run shell commands.

Setup

Prefer gam if installed:

command -v gam

If missing, install one of:

npm install -g git-as-memory
pip install git-as-memory

No global install:

npx git-as-memory --help
python -m git_as_memory.cli --help

All commands require a Git repo. If --repo is omitted, use the current working repo.

Initialize once per repo; it is idempotent:

gam init --repo /path/to/repo

Memory Policy

Write memory only for stable, reusable information.

Write when:

• The user explicitly says to remember something.
• A stable user preference appears.
• A project convention, workflow, or decision is discovered.
• A recurring bug, workaround, tool behavior, or operational lesson is learned.
• A session produces a compact conclusion that future agents should reuse.

Do not write:

• Secrets, API keys, passwords, tokens, cookies, credentials, private auth material.
• Large raw transcripts or noisy logs.
• One-off task details with no future value.
• Unverified guesses unless --type hypothesis.
• Content that belongs in source files, docs, issues, or tests instead of memory.

Before writing:

1. Search for related memory first:

   gam search "<keywords>" --repo /path/to/repo
   

2. If a related memory exists, update the same stable id.
3. If not, create a concise new memory.
4. Always include --source explaining where the memory came from.

After writing, report the memory key:

<type>/<id>

Types

Use a small, consistent type set:

• entity: user, project, organization, tool, or other entity preference/profile.
• semantic: durable fact, rule, convention, decision, or technical lesson.
• episodic: compact summary of a task/session/event.
• working: short-lived task context that may be deleted later.
• hypothesis: unverified inference that should be confirmed before acting on strongly.

Id Rules

Use stable kebab-case ids. Prefer names that future agents can guess.

Good:

user-preference-concise-answers
project-release-workflow
openclaw-memory-policy
git-as-memory-storage-layout

Avoid random ids unless there is no stable concept.

Core Commands

Write

gam write "User prefers concise technical answers with concrete commands." \
  --repo /path/to/repo \
  --type entity \
  --id user-preference-concise-answers \
  --tag user \
  --tag preference \
  --source "User corrected the agent for over-explaining and asked for practical output."

Multi-line:

printf '%s\n' "Decision summary..." | gam write --stdin \
  --repo /path/to/repo \
  --type semantic \
  --id project-decision-example \
  --source "Summarized from the current implementation session."

Read

Use read when you know the key:

gam read entity/user-preference-concise-answers --repo /path/to/repo

show is equivalent when using id plus optional type:

gam show user-preference-concise-answers --type entity --repo /path/to/repo

Search

Use search for content lookup:

gam search "release workflow" --repo /path/to/repo
gam search "concise answers" --repo /path/to/repo --json

Search is local substring matching over memory content, tags, metadata, and source text.

Glob

Use glob for memory key lookup, not arbitrary working-tree files. It matches <type>/<id> and bare ids:

gam glob "entity/*" --repo /path/to/repo
gam glob "user-*" --repo /path/to/repo
gam glob "*release*" --repo /path/to/repo

Use --files only for debugging the underlying Git tree:

gam glob "entity/*" --files --repo /path/to/repo

List

gam list --repo /path/to/repo
gam list --repo /path/to/repo --json

History and Audit

gam history user-preference-concise-answers --type entity --repo /path/to/repo

Direct Git inspection:

git -C /path/to/repo log --oneline refs/git-as-memory/memory/v1
git -C /path/to/repo ls-tree -r --name-only refs/git-as-memory/memory/v1

Delete

Prefer soft delete:

gam delete user-preference-concise-answers --type entity --repo /path/to/repo

Use purge only when the user explicitly asks to remove the current visible files:

gam purge user-preference-concise-answers --type entity --repo /path/to/repo

Agent Workflow

When starting a task in a repo:

1. If memory may matter, run targeted search:

   gam search "<project/tool/user keywords>" --repo /path/to/repo
   

2. Read only relevant matches.
3. Do not bulk-load all memory unless the user asks for an audit.

When a durable lesson appears:

1. Decide if it meets the write policy.
2. Search for duplicates.
3. Write or update one stable memory id.
4. Report the key and a one-line summary.

When the user asks "what do you remember?":

1. Use gam list, gam glob, or gam search.
2. Use gam read for relevant keys.
3. Include gam history only if provenance or evolution matters.

Output Discipline

After a memory write, respond briefly:

Remembered: entity/user-preference-concise-answers

If you decide not to write memory, say why only when useful:

Not writing memory: this is a one-off task detail.