sage-memory

name	sage-memory
description	Captures and recalls durable context for AI agents — architecture decisions, user preferences, debugging insights, conventions, anything worth remembering across sessions. Teaches the agent when to remember (store findings during work), when to recall (search memory at session start and task start), and how to learn (structured knowledge capture via sage learn). Use when the user mentions memory, remember, recall, learn, capture knowledge, onboard to codebase, or when starting any session where sage-memory MCP tools are available.
version	1.2.0
type	process

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:

---
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