sage-memory

<!-- Fallback copy — sage's vendored prose for users without the sage-memory MCP package installed. Canonical version: ships with sage-memory >= 0.8.0 and is deployed automatically by `sage update` (which runs `sage-memory install-skills` when the package is present). Edits here only affect users who don't have sage-memory installed. To override locally for everyone: create a project-level skill under .claude/skills/ with a different name. --> # Memory Make knowledge persistent across sessions. Three layers — two automatic, one user-triggered. Works with sage-memory MCP (full capability) or filesystem fallback (reduced but functional). ## Capabilities by Backend | Capability | MCP | Files | |------------|-----|-------| | Store knowledge | ✅ `sage_memory_store` | ✅ `.sage-memory/` files | | Search by keyword | ✅ BM25 ranked | ⚠️ filename scan only | | Update existing | ✅ `sage_memory_update` | ✅ edit file | | Delete | ✅ `sage_memory_delete` | ✅ delete file | | Browse / list | ✅ `sage_memory_list` with tag filter | ✅ directory listing | | Link related memories | ✅ `sage_memory_link` | ⚠️ `relations:` frontmatter (see sage-ontology skill) | | Multi-hop graph traversal | ✅ `sage_memory_graph` | ❌ single-hop scan only | | Tag filtering | ✅ `filter_tags` | ⚠️ frontmatter scan | | Deduplication | ✅ SHA-256 automatic | ⚠️ manual (check filenames) | **How to detect backend:** At session start, call `sage_memory_set_project` with the current project root path. If it responds, use MCP for the rest of the session. If the call fails or the tool doesn't exist, fall back to `.sage-memory/` files. Don't announce either outcome — just use whichever works. ## File Fallback Format All three skills (sage-memory, sage-ontology, sage-self-learning) share the same directory and file format when MCP is unavailable. **Location:** `.sage-memory/` at the project root. ``` .sage-memory/ ├── payment-saga-orchestration.md ├── jwt-auth-refresh-tokens.md ├── lrn-stripe-webhook-raw-body.md ├── ont-task-a1b2-fix-payment-timeout.md └── ... ``` **Filename** = kebab-case title (the primary retrieval key without MCP). Prefix with `lrn-` for learnings, `ont-` for ontology entries, no prefix for regular knowledge. **Each file:** ```markdown --- tags: [billing, architecture, saga] type: knowledge scope: project created: 2026-03-20 --- The billing service uses a saga pattern for multi-step payment processing. PaymentOrchestrator coordinates between StripeGateway, LedgerService, and NotificationService. ``` **type values:** `knowledge` (default), `learning`, `ontology` **Recall without MCP:** Read the `.sage-memory/` directory listing. Filenames are titles — scan them for relevance. Read only the files that match the current task. For learnings, look for `lrn-` prefix. For ontology, look for `ont-` prefix. ## Layer 1: Automatic Recall At session start and task start, search for relevant context. ### When to Search - **Session start.** First, call `sage_memory_set_project` with the current project root path. Then search for architecture, conventions, recent decisions. Memory is cheaper than re-reading source code. - **Task start.** Search for related prior work, debugging insights, architecture decisions that constrain the approach. - **Skill activation.** Search for prior findings in the activated domain. ### How to Search **With MCP:** ``` sage_memory_search(query: "billing service architecture patterns", limit: 5) ``` Use `filter_tags` for namespace isolation, `tags` for soft boosting: ``` sage_memory_search(query: "auth patterns", filter_tags: ["self-learning"], limit: 5) sage_memory_search(query: "checkout flow", tags: ["billing"], limit: 5) ``` **With files:** Read the `.sage-memory/` directory listing. Identify filenames relevant to the current task. Read those files for content. For a broad search, list all files and scan names. For focused search, look for specific keywords in filenames. ### Enriched Recall with Graph (MCP only) When you find a key memory via search, expand context: ``` sage_memory_graph(id: "<memory_id>", direction: "outbound", depth: 1) ``` This reveals what the memory depends on or connects to. One call replaces N sequential searches. **Skip this step when using files.** ### Reporting What You Found **Memories found:** State what you know from previous sessions. Be specific — "From previous work, I know this project uses a saga pattern for payments with compensating transactions." **Nothing found:** Say nothing. Don't announce empty results. **Always attribute.** "Based on what we learned in previous sessions..." ## Layer 2: Automatic Remember During any workflow, store valuable findings for future sessions. ### What to Store Store **insights**, not **facts**. Store what requires understanding. **SHOULD store:** architecture decisions with rationale, discovered conventions, non-obvious behavior, debugging root causes, domain knowledge from research, integration gotchas. **SHOULD NOT store:** anything re-readable from source code, temporary task state, obvious patterns, trivial fixes, user preferences (global scope). ### How to Store **With MCP:** ``` sage_memory_store( content: "The billing service uses a saga pattern for multi-step payment processing. PaymentOrchestrator coordinates between StripeGateway, LedgerService, and NotificationService.", title: "Payment saga orchestration via PaymentOrchestrator with 3 services", tags: ["billing", "saga", "payments", "architecture"], scope: "project" ) ``` **With files:** Create a file in `.sage-memory/`: ``` File: .sage-memory/payment-saga-orchestration.md --- tags: [billing, saga, payments, architecture] type: knowledge scope: project created: 2026-03-20 --- The billing service uses a saga pattern for multi-step payment processing. PaymentOrchestrator coordinates between StripeGateway, LedgerService, and NotificationService. ``` ### Extract Before Store (0.9+) Identify the key entities (technologies, services, modules, components, people) in the content and pass them as `entities` so they appear in the knowledge graph. sage-memory does NOT auto-extract by default — you provide the structure, sage-memory builds the index. This works even without an LLM API key set for sage-memory; your own agent's LLM is doing the extraction. ``` sage_memory_store( content: "The billing service uses a saga pattern. PaymentOrchestrator coordinates between StripeGateway, LedgerService, and NotificationService.", title: "Payment saga orchestration via PaymentOrchestrator", tags: ["billing", "saga", "architecture"], entities: [ {name: "PaymentOrchestrator", type: "CONCEPT"}, {name: "StripeGateway", type: "CONCEPT"}, {name: "LedgerService", type: "CONCEPT"}, {name: "Stripe", type: "TECHNOLOGY"} ], relations: [ {from: "PaymentOrchestrator", to: "StripeGateway", rel: "depends_on"}, {from: "PaymentOrchestrator", to: "LedgerService", rel: "depends_on"}, {from: "StripeGateway", to: "Stripe", rel: "depends_on"} ], scope: "project" ) ``` **Entity types:** PERSON, CONCEPT, TECHNOLOGY, PROJECT, EVENT, OTHER. **Relation types:** mentions, relates_to, contains, depends_on, contradicts, derived_from, implements, references, supersedes, alternative_to. **Suggested links.** The response includes a `suggested_links` field listing existing memories whose content overlaps with what you just stored. Use it to call `sage_memory_link` when the connection is meaningful — e.g., linking new architecture knowledge to an existing ontology Task entity. **With files:** entities/relations aren't surfaced in file-mode. Mention important relationships in the content body instead. ### Linking Related Memories (MCP only) When storing memories about connected components, create edges: ``` sage_memory_link( source_id: "<payment_service_id>", target_id: "<stripe_gateway_id>", relation: "depends_on" ) ``` **With files:** Skip linking. Mention related entries in the content body if the connection is important: "Related: see jwt-auth-refresh-tokens for the authentication layer this service uses." ### Cross-Reference Scanned Code (0.11+) If `sage-memory scan-codebase` has run, every source file in the project is also a memory tagged `["codebase", "file", "<lang>"]`. Use this BEFORE storing prose to enrich the knowledge graph. **Workflow when storing architecture / design memories:** 1. **Run the scan once at session start** (if not already done): ``` sage-memory scan-codebase ``` Or invoke via MCP: `sage_memory_scan_codebase`. 2. **Locate the files your memory references:** ``` sage_memory_search( query: "PaymentOrchestrator", filter_tags: ["codebase"], limit: 5 ) ``` 3. **Store the prose memory** as usual: ``` sage_memory_store( title: "Payment saga orchestration via PaymentOrchestrator", content: "PaymentOrchestrator coordinates StripeGateway, ...", tags: ["billing", "saga", "architecture"] ) ``` 4. **Link to each referenced file** so the graph surfaces this prose when an agent later touches one of those files: ``` sage_memory_link( source_id: "<prose_memory_id>", target_id: "<file_memory_id>", // from step 2 relation: "describes" ) ``` **Why bother:** file-memory ids are stable across renames (the content_hash is path-salted, but moving a file with unchanged content keeps the same row across re-scans IF the path is the same; renames create new rows but the old row stays around for search until pruned). Linking to file-memories beats embedding file paths in prose — paths rot when files move, edges don't. **When NOT to cross-reference:** for memories about decisions / processes / external systems with no code anchor, skip the link. Forcing every memory to point at code is noise. **With files:** Skip — without MCP, no graph edges. Continue using filenames in the prose content; accept that they may go stale. ### Writing Retrievable Content **Title:** 5-15 words, specific. Good: "Payment saga orchestration via PaymentOrchestrator with 3 services." Bad: "How payments work." **Content:** Explain what AND why. Use the project's actual class names, function names, domain concepts. **Tags:** 2-5 domain keywords. **Budget:** 3-8 memories per significant task. Quality over quantity. ## Layer 3: Deliberate Learning (`sage learn`) User-triggered structured knowledge capture. Produces: 1. **Memory entries** (stored via MCP or files) 2. **Knowledge report** (`.sage/docs/memory-{name}.md`) ### Broad Scan: `sage learn` 1. Read project structure, README, config files, entry points 2. Identify: stack, architecture style, key modules, conventions 3. Trace a few representative flows 4. Store 10-20 memories covering architecture, stack, conventions, key modules, and non-obvious patterns 5. **MCP only:** Link related memories using `sage_memory_link` to build a navigable architecture graph. **Files:** mention connections in content instead. 6. Produce a knowledge report at `.sage/docs/memory-{project-name}.md` ### Deep Dive: `sage learn <path>` 1. Read all files in the target path 2. Trace dependencies up to depth 3 3. Map: purpose, key components, data flow, patterns, error handling 4. Identify: risks, technical debt, non-obvious behavior 5. Store 5-10 focused memories 6. **MCP only:** Build dependency graph via `sage_memory_link`. **Files:** note dependencies in content. 7. Produce a knowledge report at `.sage/docs/memory-{name}.md` ### Knowledge Reports **Read:** `references/knowledge-report.md` for the full guide. Flexible structure. General shape: Overview, Architecture & Patterns, Key Components, Diagrams (mermaid), Insights, Recommendations, Metadata. ## Unified Knowledge Facets sage-memory, sage-ontology, and sage-self-learning are three facets of ONE knowledge system. Differentiation through tags (MCP) or `type` field (files): | Facet | MCP tags | File type | Purpose | |-------|----------|-----------|---------| | Knowledge | domain tags | `knowledge` | Architecture, conventions | | Structure | `["ontology", ...]` | `ontology` | Entity relationships | | Warnings | `["self-learning", ...]` | `learning` | Mistakes, gotchas | ## Quality Principles **Memory is not a log.** Store what changes future decisions. **Specificity retrieves.** Use actual project vocabulary. **Insights over facts.** Store the WHY, not just the WHAT. **Recency matters.** Update or delete stale memories. ## References - `references/knowledge-report.md` — Knowledge report guide - `references/memory-patterns.md` — Good/bad memory examples