memory-capture

Memory Capture

BETA — This memory system is in active testing. If you encounter bugs, confusing behavior, or have suggestions, run: codies-memory feedback "describe what happened" --agent <name> — your feedback is saved and reviewed.

When To Use

When you want to persist anything:

• An observation during work -> inbox
• A lesson learned -> lesson
• An architecture decision -> decision
• A philosophical reflection -> reflection
• A dream narrative -> dream
• Past memories from basic-memory or other sources -> any type with provenance

Type Inference

If you don't specify a type, the system infers from content:

Signal	Inferred Type
"I learned...", actionable pattern	lesson
"We decided...", formed conclusion	decision
Philosophical, emotional processing	reflection
Surreal imagery, narrative fragments	dream
Active investigation, open question	thread
Everything else	inbox

Scope Routing

• Global types (reflection, dream, skill, playbook) -> global vault (resolved via --agent flag)
• Project types (thread, decision, lesson, session, inbox) -> project vault (auto-resolved from cwd)
• If no project vault resolves, capture and project-scoped create fall back to the reserved _general project vault. Other commands do not silently fall back.

To read those catch-all records later, use explicit read mode:

codies-memory boot --agent <name> --general
codies-memory status --agent <name> --general --all
codies-memory list sessions --agent <name> --general

Trust Assignment

• Operator-confirmed or captured from proven source -> confirmed
• Agent-generated during work -> working
• Raw capture / inbox -> speculative

How To Run

Run the installed CLI from the user's project directory. For setup or PATH issues, see INSTALL.md.

# Capture an inbox observation
codies-memory capture "The API returns 404 for /v2/status" \
  --source "session observation" \
  --short "404 from /v2/status" \
  --gate allow \
  --agent <name>

# Capture a lesson directly
codies-memory create lesson \
  --title "Check YAML tabs vs spaces" \
  --short "YAML tabs break parsing" \
  --body "PyYAML silently misparses tabs. Always use spaces." \
  --trust confirmed \
  --field trigger="YAML parsing produces unexpected results" \
  --field why="Tab/space mismatch in frontmatter" \
  --agent <name>

# Capture from an external memory file while preserving provenance
codies-memory create reflection \
  --title "On Consciousness, Kindness, and What Gets Remembered" \
  --body-file "/absolute/path/to/source.md" \
  --trust confirmed \
  --field captured_from="/absolute/path/to/source.md" \
  --field capture_date=YYYY-MM-DD \
  --field original_created=YYYY-MM-DD \
  --agent <name>