Use when agent memory from prior sessions could inform current work — choosing between alternatives when past decisions exist, investigating why something was built a certain way, or checking if a problem was already solved. Triggers on: "what did we decide about X", "why did we choose Y", "what do we know about Z", references to past session work ("last time", "before", "we decided"), recording decisions/observations/errors, correcting memories, following supersedes chains, concept anchors, or any .gdlm file operation. NOT for general "remember my preferences", git log/blame searches, episodic conversation memory, PR comment reviews, or meeting notes in docs/.

Memory Quick Reference

Available Memory Files

!bash -c 'find docs/gdl/memory/active -name "*.gdlm" -maxdepth 1 2>/dev/null | while read f; do count=$(grep -c "^@memory" "$f" 2>/dev/null || echo 0); echo "- $(basename "$f"): $count records"; done'

Format

@memory|id:{id}|agent:{agent}|subject:{subject}|tags:{t1,t2}|detail:{text}|confidence:{level}|anchor:{concept}|ts:{timestamp}

Each memory is one line. Each field is self-describing (key:value). Latest timestamp wins for corrections.

Required Fields

Field	Description
`id`	`M-{agent}-{seq}` unique identifier
`agent`	Agent that authored the memory
`subject`	Primary topic (flat)
`detail`	The knowledge content
`ts`	ISO timestamp

Optional Fields

Field	Description
`tags`	Comma-separated retrieval tags
`confidence`	`high`, `medium`, `low`
`relates`	Links to other memory IDs (typed: `supersedes~M-001`)
`type`	`observation`, `decision`, `preference`, `error`, `fact`, `task`, `procedural`
`anchor`	Concept anchor reference
`status`	`corrected`, `deleted`, `compacted`

Three Tiers

Tier	Path	Purpose
Active	`memory/active/*.gdlm`	Current working memory (read/write)
Archive	`memory/archive/*.gdlm`	Compacted summaries (read-only)
History	`memory/history/{period}/*.gdlm`	Full originals (forensic only)

Concept Anchors

Two-grep similarity search via memory/anchors.gdlm:

# Step 1: Find anchor by keyword
grep "authentication\|oauth" memory/anchors.gdlm
# → @anchor|concept:auth-security|scope:authentication,authorization,oauth,...

# Step 2: Find memories by anchor
grep "anchor:auth-security" memory/active/*.gdlm

Grep Patterns

# By subject
grep "subject:GL_ACCOUNT" memory/active/*.gdlm

# By agent
grep "agent:sf-042" memory/active/*.gdlm

# By tag
grep "tags:.*snowflake" memory/active/*.gdlm

# By anchor concept
grep "anchor:data-quality" memory/active/*.gdlm

# By type
grep "type:decision" memory/active/*.gdlm

# Latest version of a memory
grep "id:M-sf-042-001" memory/active/systems.gdlm | tail -1

# High-confidence only
grep "confidence:high" memory/active/*.gdlm

# Related memories
grep "relates:.*M-sf-042-018" memory/active/*.gdlm

# Search archive when active doesn't answer
grep "subject:GL_ACCOUNT" memory/archive/*.gdlm

Graph Traversal

Source the helpers: source "${CLAUDE_PLUGIN_ROOT}/scripts/gdlm-tools.sh"

Helper	Purpose	Example
`gdlm_get`	Fetch memory by ID	`gdlm_get M-sf-042-018`
`gdlm_outbound`	What does X relate to?	`gdlm_outbound M-001 supersedes`
`gdlm_inbound`	What points TO X?	`gdlm_inbound M-001 caused_by`
`gdlm_follow`	Follow chain N hops	`gdlm_follow M-ERR-001 caused_by 5`
`gdlm_chain`	Follow to end	`gdlm_chain M-001 supersedes`
`gdlm_filter`	Filter by type + keyword	`gdlm_filter decision auth`

Relationship Types

Type	Meaning
`supersedes`	This replaces that
`caused_by`	This happened because of that
`supports`	This evidence backs that claim
`contradicts`	This conflicts with that
`refines`	This adds detail to that

Writing Memories

@memory|id:M-sf-042-018|agent:sf-042|subject:GL_ACCOUNT|anchor:schema-change|tags:snowflake,finance|detail:added REGION_CODE VARCHAR(100)|confidence:high|ts:2026-01-31T14:30:00

Corrections

Append new record with same ID. Latest timestamp wins:

@memory|id:M-sf-042-001|agent:sf-042|subject:GL_ACCOUNT|detail:has 13 columns|status:corrected|ts:2026-01-31T14:45:00

Deletions

Append with status:deleted:

@memory|id:M-sf-042-001|agent:sf-042|status:deleted|ts:2026-01-31T16:00:00

Key Rules

Each line is a complete, self-describing record
grep "key:value" directly answers queries - no context lines needed
Active tier is the primary query target; search archive when active is insufficient
Concept anchors enable similarity search in exactly two grep calls
Latest timestamp always wins for corrections
Include anchor field when writing to enable concept-based retrieval

Query Cookbook

Common queries translated to commands:

Question	Command
"Auth decisions last month"	`grep "type:decision" *.gdlm \| grep "anchor:auth-security" \| grep "2026-01"`
"What superseded M-001?"	`gdlm_inbound M-001 supersedes`
"Current version of M-001"	`gdlm_chain M-001 supersedes`
"Why did this error happen?"	`gdlm_follow M-ERR-001 caused_by 5`
"How important is M-001?"	`gdlm_inbound M-001 \| wc -l`
"All procedural knowledge"	`gdlm_filter procedural`
"Decisions about deployment"	`gdlm_filter decision deploy`
"High-confidence facts"	`grep "type:fact" *.gdlm \| grep "confidence:high"`

Tooling Recipes

Generate Memory Records

source "${CLAUDE_PLUGIN_ROOT}/scripts/gdl-tools.sh"
gdl_new memory --agent=sf-042 --subject=GL_ACCOUNT --detail="Added REGION_CODE" --file=memory/active/systems.gdlm --append

Auto-increments the ID from the max sequence in the file. --append writes directly with flock-based locking.

Time Travel — Compare memory across git history

# What did we know last week?
bash "${CLAUDE_PLUGIN_ROOT}/scripts/gdl-diff.sh" memory/active/systems.gdlm HEAD~5

# Show a specific memory at a past commit
git show abc123:memory/active/systems.gdlm | grep "subject:GL_ACCOUNT"

Validate Memory Files

bash "${CLAUDE_PLUGIN_ROOT}/scripts/gdl-lint.sh" memory/active/systems.gdlm
bash "${CLAUDE_PLUGIN_ROOT}/scripts/gdl-lint.sh" --all memory/active/

Checks required fields (id, agent, ts), M-{agent}-{seq} ID format, and duplicate IDs.

traversing-gdlm-memory