xoai/sage-using-memory

Using memory

Sage has its own memory. It is not the platform's native memory (MEMORY.md, feedback files, and the like). Storing a Sage learning in the platform's memory puts it where no other Sage session will look for it.

Storage target: the sage_memory_store() MCP tool. Fallback: .sage-memory/ markdown files when the MCP server is unavailable.

Search before work (Rule 1A)

Before writing a spec, a plan, or an ADR — or before starting an investigation — search memory. This is mandatory for Standard+ work and skipped only for Tier 1.

Two searches minimum:

1. Domain search — the task's domain keywords, limit: 5.
2. Self-learning search — the same query with filter_tags: ["self-learning"], limit: 5.

The second search is the one people skip, and it is the one that pays. It is where "we tried that and it did not work" lives.

Parameter types (get these right or the call fails)

The MCP schema is strict, and the failure mode is a confusing error rather than a graceful degradation:

| Parameter | Type | Pass | Do not pass | |---|---|---|---| | query | string | "cache eviction" | — | | limit | integer | 5 | "5" | | filter_tags | array of strings | ["self-learning"] | '["self-learning"]' | | tags | array of strings | ["gotcha", "redis"] | '["gotcha"]' |

Capture corrections (Rule 6)

When a learning moment happens, store it before proceeding. This is automatic, not optional — the correction you do not write down is the one you repeat in three weeks with a straight face.

What counts as a learning moment

| Trigger | Type | |---|---| | The user corrects your approach | correction — MANDATORY, never skip | | You tried 3+ approaches before one worked | gotcha | | Root cause turned out to be non-obvious | gotcha | | You discovered an undocumented project convention | convention | | An API or library behaved differently than expected | api-drift | | A test failed for a non-obvious reason | error-fix |

Format

• Title: prefixed [LRN:<type>]
• Content: four parts — what happened · why it was wrong · what is correct · the prevention rule
• Tags: self-learning + the type + domain keywords

The four-part body matters more than it looks. "Redis eviction is LRU here" is a fact and will be forgotten. "We used LFU, it thrashed under burst traffic because the counters never decayed, so this codebase pins LRU — check cache.py before changing eviction" is a rule, and it survives.

Why the store call comes before the next step

The temptation is to finish the task and store the learning afterwards. There is no afterwards. The session ends, the context window closes, and the learning that existed only as an intention is gone. Store it while it is still true.