sage-memory

Files (1)

• SKILL.md

SKILL.md (first lines)

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

From xoai/sage, MIT.

More from xoai/sage