remember

record memories for future retrieval. no database—files are the memory, retrieved via grep.

configuration

set $MEMORY_ROOT to your memory directory:

bash

export MEMORY_ROOT="$HOME/commonplace/01_files"

if unset, defaults to ~/commonplace/01_files/. customize paths in examples below to match your setup.

when to use

•learned something that would help in future sessions
•discovered a pattern or gotcha worth preserving
•captured context that will otherwise be lost when this thread ends
•built something worth documenting for reuse

memory anatomy

memories follow date-prefixed naming with two agent-specific requirements:

•source__agent tag — required, marks this as agent-generated
•frontmatter with thread URL — records where learning happened

code

$MEMORY_ROOT/YYYY-MM-DD description -- source__agent.md

yaml

---
source: https://ampcode.com/threads/T-xxxxx
keywords:
  - relevant
  - searchable
  - terms
---

keywords are freeform tags for retrieval.

content

write for your future self:

•the insight
•why it matters
•how to apply it

link to related memories with markdown links: [note name]($MEMORY_ROOT/note name.md)

belief: connections between ideas compound value. an isolated fact is less useful than one linked to context.

examples

pattern learned

date-prefixed naming makes chronological browsing trivial. insight in body, not filename:

markdown

# kanata timing on macos

homerow mods feel laggy with default timing. 150ms tap timeout + 250ms hold 
works well. the `charmod` template with fast-typing detection prevents 
misfires during rapid typing.

key insight: smart typing detection (`key-timing 3 less-than 250`) disables 
homerow mods when typing fast, re-enables when pausing.

gotcha discovered

gotchas prevent repeat debugging sessions:

markdown

# nix overlay ordering

overlays apply left-to-right. if overlay B depends on packages from overlay A,
A must come first in the list. this bit us when unstable overlay wasn't 
available to later overlays.

fix: ensure `unstable.nix` is first in the overlays list.

decision recorded

decisions capture the tradeoffs considered, not just the choice made:

markdown

# chose grep over sqlite for memory retrieval

considered basic-memory (sqlite + vectors) but it kept corrupting on sync.
grep on flat files is:
- unbreakable (files are source of truth)
- syncthing-friendly
- human-readable
- fast enough for thousands of files

tradeoff: no semantic search. acceptable given good naming/tagging.

retrieval

check for relevant memories before starting work:

bash

# find agent memories about a topic
ls "$MEMORY_ROOT" | grep source__agent | grep -i topic

# search memory content
rg "topic" "$MEMORY_ROOT"/*source__agent*.md

# recent memories
ls -t "$MEMORY_ROOT"/*source__agent*.md | head -20

what NOT to remember

•session-specific context (use thread continuation instead)
•things already documented elsewhere (link instead)
•trivial facts (not worth the file overhead)