Session Memory

---
name: session-memory
description: "End-of-session memory capture -- analyzes session for decisions, outcomes, and patterns worth remembering, then stores confirmed items via Pensyve. Use when ending a work session or when the user wants to capture what was learned."
version: 1.0.0
---

# Session Memory Capture

Analyze the current session for memorable decisions, outcomes, and patterns, then store confirmed items in Pensyve memory.

## Instructions

> **Note:** As of the working-memory substrate update, most memorable items are already captured in-flight during the session by memory-woven skills (memory-informed-debug, memory-informed-design, memory-informed-longitudinal-work) and by the signal buffer's in-flight triggers. This skill handles **residuals** — items that weren't captured in-flight and still deserve to be saved. Before presenting candidates, call `pensyve_inspect` to see what's already been captured this session and skip duplicates.

When this skill is invoked (typically at the end of a coding session), follow these steps:

### Step 1: Analyze the Session

Review the current session conversation for three categories of memorable content:

**Decisions** (confidence: 0.9):

- Architecture or design choices ("we decided to use X over Y because...")
- Technology selections ("chose SQLite for the MVP because...")
- API design decisions ("the endpoint should accept JSON, not form data")
- Tradeoff resolutions ("accepted O(n) scan because dataset is small")

**Outcomes** (confidence: 0.8):

- Bug fixes and their root causes ("the auth failure was caused by expired refresh tokens")
- Successful approaches ("fixed the race condition by adding a mutex")
- Failed approaches ("tried connection pooling but it caused deadlocks")
- Performance findings ("query time dropped from 2s to 50ms after adding the index")

**Patterns** (confidence: 0.7):

- Recurring issues ("this is the third time the cache invalidation was wrong")
- Workflow discoveries ("running tests before migrations catches schema drift")
- Cross-cutting observations ("all the timeout errors trace back to the DNS resolver")

### Step 2: Filter for Significance

Skip routine, low-signal content that does not warrant long-term storage:

- **Check for duplicates via recall.** For each candidate, call `pensyve_recall` with `query: <candidate fact text>`, `entity: <candidate's entity>`, `limit: 3`. If any returned memory has a score ≥0.85 against the candidate, skip it as a likely duplicate. Note: `pensyve_inspect` cannot filter by `episode_id` (its params are `entity`, `memory_type?`, `limit?` only), so this dedup check uses semantic similarity against the entity's full memory set rather than true session-scoped filtering. Consequence: very similar items captured in prior sessions will also trigger the skip — acceptable for avoiding genuine duplicates, but may miss newly-phrased variants of old memories.

- Simple typo fixes or formatting changes
- Routine file edits with no architectural significance
- Standard boilerplate or scaffolding without decisions
- Repeated application of known patterns (unless the pattern itself is new)
- Content that is already stored in Pensyve (check via `pensyve_recall` with targeted queries)

### Step 3: Present Candidates for Confirmation

Present the candidate memories to the user in a structured format:

> **Session Memory Candidates**
>
> **Decisions** (confidence: 0.9):
>
> 1. `auth-service`: Chose RS256 over HS256 for JWT signing to support key rotation
> 2. `api-design`: POST endpoints return 201 with the created resource, not 200
>
> **Outcomes** (confidence: 0.8): 3. `database`: Migration script fails silently when Python < 3.11 -- added version check
>
> **Patterns** (confidence: 0.7): 4. `testing`: Integration tests that touch the filesystem need tmpdir cleanup
>
> Which items should I store? (e.g., "all", "1,3", "none")

### Step 4: Store Confirmed Items

For each confirmed item, decide the storage type:

**Episodic (observations)** -- things that happened this session. Call `pensyve_observe` with:

- `episode_id`: From the session state (set by SessionStart hook)
- `content`: The observation text
- `source_entity`: `"claude-code"`
- `about_entity`: The inferred entity name (lowercase, hyphenated)
- `content_type`: `"text"` for decisions/patterns, `"code"` for code-related outcomes

Use for: bug fixes, failed approaches, debugging outcomes, performance findings, session-specific events.

**Semantic (durable facts)** -- truths that persist beyond this session. Call `pensyve_remember` with:

- `entity`: The inferred entity name (lowercase, hyphenated)
- `fact`: The memory text
- `confidence`: 0.9 for decisions, 0.8 for outcomes, 0.7 for patterns

Use for: architecture decisions, technology choices, user preferences, project conventions.

When in doubt, prefer `pensyve_observe` -- the consolidation engine promotes recurring patterns to semantic facts automatically.

Before storing, run `pensyve_recall` with a query matching the candidate fact to check for duplicates. If a highly similar memory already exists (score > 0.85), skip it and inform the user.

### Step 5: Report Results

After storing, summarize what was saved:

> **Stored 3 memories:**
>
> - `auth-service`: Chose RS256 over HS256 for JWT signing (confidence: 0.9)
> - `database`: Migration script fails silently when Python < 3.11 (confidence: 0.8)
> - `testing`: Integration tests need tmpdir cleanup (confidence: 0.7)

## Constraints

- **NEVER auto-store.** Every candidate MUST be presented to the user for confirmation before calling `pensyve_remember`. This is a hard requirement.
- **Never read or write `.claude/` memory files.** All memory operations go through the Pensyve MCP tools exclusively.
- Entity names MUST be lowercase and hyphenated.
- Do not store secrets, API keys, passwords, or credentials. Warn the user if a candidate appears to contain sensitive data.
- If the session has no significant content worth remembering, say so clearly rather than forcing low-quality memories.
- When in doubt about whether something is significant, include it as a candidate and let the user decide.

## Error Handling

- If `pensyve_remember` fails, display the error and continue with remaining items.
- If `pensyve_recall` (duplicate check) fails, proceed with storage but note that duplicate checking was skipped.
- If the MCP server is not connected, inform the user and suggest checking their MCP server configuration.