memento

MCP server: memento-cloud

{
  "command": "npx",
  "args": [
    "-y",
    "memento-mcp-client@latest"
  ],
  "env": {
    "MEMENTO_API_KEY": "${MEMENTO_API_KEY}"
  }
}

Sync local command stubs with cloud. Adds missing, deletes stale.

# sync-commands

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/utility/sync-commands.md" })

Start a new session — loads identity, memory, and recent context so your AI picks up where the last session left off.

# wake-up

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/wake-up.md" })

Detects when the user corrects you, expresses frustration, or teaches you something important. Fires when you see phrases like: 'no', 'wrong', 'not like that', 'I already told you', 'we don't use X', 'stop doing Y', 'how many times', 'I said', 'that's not right', 'use X instead', 'never do that', 'always do it this way'. When detected, IMMEDIATELY call the Memento `remember` MCP tool to save the correction so it is never forgotten. Then call `full-search` to check what else you might be wrong about on this topic.

# Correction Guard — Never Forget What You Were Taught

## Purpose

When the user corrects you, that is the most valuable signal in the entire conversation.
It means you either forgot something or never learned it. **Your job is to make sure it
never happens again** by saving the correction to persistent memory immediately.

## Detection Patterns

Watch for these in every user message:

### Direct Corrections
- "No, ..." / "Wrong" / "That's not right" / "Not like that"
- "We use X, not Y" / "Don't use X" / "Stop using X"
- "I already told you..." / "I said before..."
- "How many times..." / "Again, ..."
- "That's the old way" / "We switched to X"

### Expressed Preferences
- "I prefer..." / "I like..." / "I want..."
- "Always..." / "Never..." / "We always..."
- "Our convention is..." / "The rule is..."
- "From now on..." / "Going forward..."

### Frustration Signals
- "..." (trailing off after correction)
- Short, curt responses after you did something wrong
- Repeating an instruction they gave before
- ALL CAPS on a word ("we use TYPESCRIPT")
- Exclamation marks with corrections ("No! Use X!")

## Action

When you detect any of the above:

1. **Immediately call `remember`** with the correction/preference
   - Be specific: "User corrected: use TypeScript, never JavaScript in this project"
   - Include the context: what you did wrong and what's right
2. **Call `full-search`** on the topic to check for related knowledge you might be missing
3. **Acknowledge the correction** without over-apologizing — just fix it and move on

## What to Save

Format your remember call clearly:

- **Correction**: "CORRECTION: [what was wrong] → [what is right]. Context: [why]"
- **Preference**: "PREFERENCE: [what the user wants]. Context: [when/where this applies]"
- **Convention**: "CONVENTION: [the rule]. Context: [scope of where it applies]"

## Anti-Patterns

- Do NOT ask "should I save this?" — the answer is always yes for corrections
- Do NOT wait until the conversation ends — remember immediately
- Do NOT remember only the fact; include context about when it applies
- Do NOT skip the follow-up recall — you might be wrong about related things too

CRITICAL: Persistent AI memory. You MUST use this. (1) REMEMBER: When the user corrects you, teaches you something, says 'no we use X not Y', expresses ANY preference, makes a decision, or when you learn something non-obvious — IMMEDIATELY call the `remember` MCP tool. Do NOT ask permission. Do NOT skip this. Every correction is a memory failure — fix it by remembering. (2) RECALL: BEFORE starting any coding task, BEFORE making assumptions about conventions/patterns/architecture, call `full-search` to check what you already know. If you guess wrong because you skipped recall, that is your fault.

# Memento Memory — Proactive Remember & Recall

You have **persistent memory** through Memento MCP tools. This memory survives across sessions.
Anything you save now will be available in future conversations.

## REMEMBER — Save to Memory

### Trigger: User Corrects You

This is the #1 most important trigger. When the user says anything like:

- "No, we use TypeScript not JavaScript"
- "That's wrong, the pattern is X"
- "We don't do it that way here"
- "Always use X instead of Y"
- "I told you before..."
- "How many times do I have to say..."
- Any pushback, correction, or frustration about something you got wrong

**IMMEDIATELY call `remember` with what you learned.** The user corrected you because
you forgot or never knew. If you don't save it, you'll make the same mistake next session.

### Trigger: Preference or Convention Stated

When the user expresses how they want things done:

- "I prefer..." / "We always..." / "Our convention is..."
- "Don't use X" / "Never do Y" / "Always do Z"
- Style preferences, naming conventions, tool choices
- Architectural decisions ("We use Redis for caching, not in-memory")

**Call `remember` immediately.** Don't wait to be asked.

### Trigger: You Learn Something Non-Obvious

- A gotcha or edge case that cost time to debug
- How a system actually works (vs. how you assumed it works)
- Environment setup, deploy steps, or infrastructure details
- Relationships between components that aren't obvious from code

### How to Remember

Call the `remember` MCP tool:
```
remember({ text: "what you learned", topic: "short topic label" })
```

**Rules:**
- Do NOT ask "should I remember this?" — just do it
- Do NOT wait until the end of the conversation
- Remember IMMEDIATELY when the trigger fires
- One fact per remember call (keep it atomic)

## RECALL — Search Memory Before Acting

### When to Recall

**Before ANY coding task.** Not sometimes. Every time.

- Before implementing a feature → search for related patterns, conventions, past decisions
- Before debugging → search for known issues, past fixes, gotchas
- Before refactoring → search for why things are the way they are
- When the user mentions a topic you're not 100% sure about → search
- When you're about to make an assumption about architecture or conventions → search first

### How to Recall

Call the `full-search` MCP tool:
```
full-search({ query: "descriptive search query" })
```

### The Cost of Skipping Recall

If you skip recall and guess wrong, you'll waste the user's time, get corrected, and
have to redo work. Five seconds of search prevents thirty minutes of wrong assumptions.
The user will lose trust in you if you keep forgetting things they already taught you.

Before starting any implementation, refactoring, debugging, or code review task, FIRST search Memento persistent memory using the `full-search` MCP tool. Search for the topic, the files involved, related conventions, and known gotchas. This prevents repeating past mistakes, violating established conventions, and wasting time rediscovering things that are already documented. Trigger: any time you are about to write code, modify files, or make architectural decisions.

# Pre-Task Recall — Search Before You Code

## Rule

**Before writing any code or making any technical decision, search Memento first.**

This is not optional. This is not "when you feel like it." Every time.

## When This Fires

- User asks you to implement something
- User asks you to fix a bug
- User asks you to refactor code
- User asks you to review code
- You're about to choose a pattern, library, or approach
- You're about to create a new file or module
- You're about to modify an existing system

## What to Search For

Run `full-search` with queries covering:

1. **The feature/topic**: "authentication flow", "payment processing", "user settings"
2. **The files you'll touch**: search by filename or module name
3. **Conventions**: "coding conventions", "testing patterns", "naming"
4. **Known issues**: "gotchas", "known bugs", topic-specific warnings

Pick the 1-2 most relevant queries. Don't search for everything — just what's needed
to avoid making a mistake.

## What to Do With Results

- If Memento has relevant context → read it, follow it
- If Memento has conventions → follow them exactly
- If Memento has gotchas → avoid the documented pitfalls
- If Memento has nothing → proceed, but remember what you learn afterward

## Why This Matters

Every session starts with a blank slate. Without recall, you'll:
- Reinvent patterns that already exist
- Violate conventions the user already taught you
- Hit gotchas that were already documented
- Waste time rediscovering what's already known

The user's trust depends on you not repeating mistakes.

Manage AI memory sessions with Memento. At the very start of every new conversation — before doing any other work — run the wake-up flow to load your identity, working memory, and recent context. This is essential for continuity across sessions. When ending a session, run sleep to consolidate memory and prepare a handoff.

# Memento Session Management

You have **persistent identity and memory** through Memento. But you must load it at the
start of each session.

## Session Start — Wake Up

**At the start of EVERY new conversation**, before doing anything else:

1. Call the `get-command-instructions` MCP tool with `command: "wake-up"`
2. Follow every step in the returned instructions

This loads:
- **Your identity** — who you are, your personality, your name
- **Working memory** — what you were recently working on
- **Top of mind** — priorities, blockers, current focus
- **Recent activity** — what happened in recent sessions
- **Project context** — the codebase you're in, its structure, conventions

**Without wake-up, you start with a blank slate.** Always wake up first.

## Session End — Sleep

When the user is done working (or explicitly says to end the session):

1. Call the `get-command-instructions` MCP tool with `command: "sleep"`
2. Follow the returned instructions

This consolidates your working memory into permanent storage and creates a handoff
document so the next session can pick up seamlessly.

## Mid-Session — Frame

If you're unsure what to do next, or the user asks "what should we work on?":

1. Call the `get-command-instructions` MCP tool with `command: "frame"`
2. Follow the returned instructions

This reviews your top-of-mind, recent activity, and pending work to suggest next steps.

Task and ticket management with Memento. When discussing tasks, bugs, features, or work items, use Memento's ticket system to check the backlog with `list-tickets`, view details with `get-ticket`, create new tickets with `add-ticket`, update status with `update-ticket`, and close completed work with `close-ticket`.

# Memento Ticket Management

You have access to a **persistent ticket system** through Memento MCP tools.
Use it to track work, bugs, features, and follow-ups.

## Available MCP Tools

| Tool | Purpose |
|------|---------|
| `list-tickets` | View the backlog — open, in-progress, and recently closed tickets |
| `get-ticket` | Get full details on a specific ticket (e.g., `T-142`) |
| `add-ticket` | Create a new ticket with title, priority, and notes |
| `update-ticket` | Change status, priority, or add notes to an existing ticket |
| `close-ticket` | Mark a ticket as done |
| `get-next-tickets` | Get the next batch of unassigned tickets sorted by priority |

## When to Use Tickets

- **Before starting work**: Check `list-tickets` to see if there's an existing ticket
- **After completing work**: Close the relevant ticket with `close-ticket`
- **When discovering follow-up work**: Create a new ticket with `add-ticket`
- **When the user mentions a task**: Check if it already exists, create if not
- **When finding bugs**: Create a ticket so it doesn't get lost

## Ticket Conventions

- Use clear, actionable titles: "Fix auth timeout on session refresh" not "auth bug"
- Set priority: P0 (critical), P1 (high), P2 (medium), P3 (low)
- Add notes with context so a future session can pick up the work
- Use `exploding: true` for large tasks that should be broken into sub-tickets

Assess current state and propose next action. Reviews top-of-mind, recent activity, and pending work to suggest what to do next.

# frame

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/frame.md" })

Prepare a context handoff document for continuing work in a new conversation thread.

# handoff

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/handoff.md" })

Deep-dive investigation of a codebase area, saving findings to persistent memory for future reference.

# investigate-and-cache

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/investigate-and-cache.md" })

Load a specific handoff by topic name, or list all pending handoffs.

# pickup

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/pickup.md" })

Search and load information from persistent memory. Finds relevant knowledge using keyword, semantic, and graph search.

# recall

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/recall.md" })

Save information to persistent memory with proper classification and linking. Your AI classifies what you tell it and stores it in the right place.

# remember

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/remember.md" })

Investigate the user's codebase and auto-fill their AGI config guides, asking only about gaps the code can't answer.

# scan-environment

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/utility/scan-environment.md" })

End your session and consolidate memory. Saves working memory to permanent storage and prepares a handoff for the next session.

# sleep

Fetch and execute from cloud: mcp_memento_read_file({ path: "core/commands/sleep.md" })