Log New Memories to Institutional Memory

When you finish a task, you usually walk away knowing things you didn't know at the start: why something was built a certain way, a trap you fell into and how you got out, how two systems actually connect. Without writing that down, the next session has to guess again — this is the write half of the loop; a memory-search step (see /alignment-harness:harness-setup, checkpoint 4) is the read half that later finds it.

The Command

This ships with a working local writer that needs nothing else installed — a plain JSON-lines file per project, no server, no external service:

node <path-to-this-skill>/scripts/save-memory.js \
  --repo "REPO_NAME" \
  --type "TYPE" \
  --context "When TRIGGER_CONDITION" \
  --lesson "WHAT_YOU_LEARNED" \
  --tags "tag1,tag2,tag3" \
  --confidence N

If you already run your own institutional-memory service (an institutional-memory tool of your own with its own search index), use its own write command instead — the shape of a good memory below is the same either way, only the storage differs.

Required Fields

Field	Description	Example
--repo	Repository or feature name	my-app, auth-system
--type	Memory category	pattern, intent, success, error, learning
--context	Trigger condition (starts with "When...")	"When creating a new user session"
--lesson	What was learned (3-5 sentences)	"Always navigate to /dashboard/{id}/session..."
--tags	Comma-separated keywords	"routing,session,navigation"
--confidence	1-10 scale	10 (verified), 8 (high), 5 (moderate)

Memory Types

Type	When to Use
pattern	Recurring code/architecture pattern
intent	Why something was built a certain way
success	Something that worked well
error	Mistake to avoid / gotcha
learning	General insight or discovery
kpi	Metrics or measurement approach

Confidence Scale

Score	Meaning
10	Verified via testing
8-9	Verified via code inspection
6-7	High confidence
1-5	Needs validation

Examples

Example from a real project (opt-in, labelled — shows the shape of a good "intent" note):

node save-memory.js \
  --repo "my-coaching-app" \
  --type "intent" \
  --context "When deciding how to gate a premium feature" \
  --lesson "Premium features show full marketing content with the action button always visible. The gate happens ON CLICK via a hook, not on render. Never hide the feature — show it, let them click, then gate." \
  --tags "premium,ux,feature-gate,intent" \
  --confidence 10

A generic pattern note:

node save-memory.js \
  --repo "my-app" \
  --type "pattern" \
  --context "When creating a new record programmatically" \
  --lesson "Always navigate to /records/{id}/edit (not just /records) so the specific record loads and the form doesn't create a duplicate on mount." \
  --tags "routing,navigation,records" \
  --confidence 10

A generic error/gotcha note:

node save-memory.js \
  --repo "my-app" \
  --type "error" \
  --context "When checking whether a user has an active subscription" \
  --lesson "There are two different 'active' states that share one confusing name — a free trial with no card, and a paid plan that's between billing cycles. Check which one a function actually means before trusting a variable called something ambiguous like 'active' or 'trial'." \
  --tags "subscription,disambiguation,critical" \
  --confidence 10

What to Capture

After completing work, save memories for:

1. Intent confirmed - What UX you built and why
2. Patterns discovered - Unique to this codebase
3. Gotchas resolved - Things you got stuck on then figured out
4. Architecture decisions - Why code is structured a certain way
5. Integration points - How systems connect

One Memory = One Thing

Keep memories atomic. If you learned 3 things, create 3 separate memories.

Storage Location

By default, memories are saved to the folder alignment-harness records memory prints, one file per repo:

<that folder>/{REPO_NAME}.jsonl

Before Adding

Search first to avoid duplicates:

node <path-to-this-skill>/scripts/search-memory.js "your topic"

Confirm it's actually searchable

The first time you set this up, prove the loop closes rather than trusting it blindly: log one memory, then search for a term from it (search-memory.js "term from your lesson") and confirm it comes back. If you've turned on memory search at setup (checkpoint 4), also ask a question that should surface it and check it shows up — that's the read half actually finding what this just wrote.