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 preferen...

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:

bash

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:

bash

command -v gam

If missing, install one of:

bash

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

No global install:

bash

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:

bash

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:

   bash

   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:

text

<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:

text

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

bash

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:

bash

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:

bash

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

show is equivalent when using id plus optional type:

bash

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

Search

Use search for content lookup:

bash

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:

bash

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:

bash

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

List

bash

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

History and Audit

bash

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

Direct Git inspection:

bash

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:

bash

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:

bash

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:

   bash

   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:

text

Remembered: entity/user-preference-concise-answers

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

text

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