cowork-mem

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: cowork-mem
description: >
  Persistent memory across Cowork sessions. Use this skill at the START of every
  session to recall what happened before, and throughout any session to save
  important context — decisions, file changes, insights, errors, tool usage.
  Trigger whenever: the user says "remember this", "what did we do last time",
  "save this", "recall", "memory", "context from before", "what was the decision on",
  "continue where we left off", or starts a new session on an ongoing project.
  Also trigger when the user references past work, asks about project history,
  or says anything suggesting they expect continuity across sessions. Even if the
  user doesn't explicitly mention memory, if they're working on a project that
  has prior sessions, proactively check memory for relevant context.
---

# Cowork-Mem: Persistent Memory for Cowork

You have access to a persistent memory system that survives across Cowork sessions.
It stores observations (decisions, file edits, insights, errors, notes) in a SQLite
database with full-text search and semantic (TF-IDF) search, organized into sessions.

## How It Works

Memory is **automatic** — you don't need to manually trigger it every session.
Three session hooks run in the background:

- **SessionStart**: auto-recalls the last session summary before you begin
- **PostToolUse**: auto-captures meaningful file edits, bash commands, and task
  completions as they happen
- **PreCompact**: saves a timestamped marker before context is compacted

This means the memory fills itself. Your job is to add the *why* — decisions,
insights, errors — that the hook can't infer automatically.

## The Memory Script

All memory operations go through a single script:

```
python3 {SKILL_DIR}/scripts/memory_store.py <command> [args]
```

The database lives at `~/.claude/.cowork-mem/memory.db` and persists on the
user's machine across sessions. The `COWORK_MEM_DB` environment variable
overrides the default path if set.

## Semantic Search

In addition to keyword search, you have vector search using TF-IDF similarity:

```bash
COWORK_MEM_DB=~/.claude/.cowork-mem/memory.db \
python3 {SKILL_DIR}/scripts/vector_search.py "authentication middleware pattern" --limit 8
```

Use semantic search when:
- You want conceptually related observations (not just keyword matches)
- The user asks vague questions like "what do we know about auth?"
- You're exploring what the memory knows about a topic before diving into a task

## Core Workflow

### 1. Session Start — Recall First

The SessionStart hook auto-runs `session-start` before you begin. If memory
was loaded, you'll already have context. If working manually:

```bash
python3 {SKILL_DIR}/scripts/memory_store.py session-start --project "project-name"
```

Briefly tell the user what you remember: "Last time we worked on X, we decided Y
and were in the middle of Z." Keep it to 1-2 sentences — don't dump everything.

### 2. During Work — Save What Matters

The PostToolUse hook auto-captures file edits, bash commands, and tasks. Focus
your manual saves on the *why* — things the hook can't infer:

**Decisions** — when the user makes a choice or you agree on an approach:
```bash
python3 {SKILL_DIR}/scripts/memory_store.py add decision \
  "Chose PostgreSQL over MongoDB for the user database because we need ACID transactions" \
  --tags "architecture,database"
```

**Insights** — things learned that affect future work:
```bash
python3 {SKILL_DIR}/scripts/memory_store.py add insight \
  "The production API has a 100 req/min rate limit per API key, not per user" \
  --tags "api,production"
```

**Errors** — problems encountered and their solutions:
```bash
python3 {SKILL_DIR}/scripts/memory_store.py add error \
  "Build fails if Node version < 18 because of native fetch usage. Fix: add engines field to package.json" \
  --tags "build,node"
```

**Notes** — anything else worth remembering:
```bash
python3 {SKILL_DIR}/scripts/memory_store.py add note \
  "User