Observations

Observations are the unit of memory in statefulmemory: a typed note with a title, content, optional session, and optional code anchors. They live in per-project SQLite under ~/.statefulmemory/ and are searchable with BM25 and dense vectors.

When to use it

• After a decision, bug fix, or correction you want the next session to see
• When an agent should stop rediscovering the same preference
• Before ending a coding session (batch a few high-value notes)

Save

statefulmemory obs save \
  --type decision \
  --title "use pgx not GORM" \
  --content "Team prefers raw SQL via pgx for this service" \
  --session "$(uuidgen)"

Flag	Purpose
--type	decision, fact, pattern, fix, note, …
--title	Short label (shown in lists and search)
--content	Body; pass - to read from stdin
--session	Session id (create one with statefulmemory session start or uuidgen)
--topic	Topic key for supersession / grouping
--anchor	Repeatable path::symbol (see Anchors & verify)
--scope	Usually project

Browse

statefulmemory obs recent --limit 10
statefulmemory obs get <id-or-sync-id>
statefulmemory obs history <id>       # supersession chain
statefulmemory obs relations <id>     # graph edges (conflicts, supersedes, …)

Background maintenance

statefulmemory obs reextract [--since <rfc3339>]   # re-queue fact extraction (needs LLM CLI)
statefulmemory obs reindex [--force]               # re-embed / quantize vectors

How it fits

Saved observations feed search & context, Decide, and MCP memory_add / memory_recent. Anchored ones are checked by verify. Bulk backup uses .mem archives.

Troubleshooting

Symptom	Fix
Exit 5: no project	Run inside a git repo or set STATEFULMEMORY_PROJECT
Save succeeds but search empty	Wait for embed worker, or statefulmemory obs reindex
Duplicate titles keep stacking	Enable conflict.enabled or use a shared --topic