cowork-mem

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:

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:

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:

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:

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:

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:

python3 {SKILL_DIR}/scripts/memory_store.py add note \
  "User prefers tabs over spaces, 80 char line width, and dislikes ternary operators" \
  --tags "preferences,style"

What to save vs. what to skip

The hook handles what happened. You handle why it matters.

Save: architectural decisions, non-obvious constraints, user preferences, hard-won debugging insights, things that took multiple attempts.

Skip: routine operations already captured by the hook (file reads, directory listings, standard installs).

Privacy

If the user wraps something in <private> tags, the content is stored but excluded from search results. Useful for sensitive data that provides context but shouldn't surface casually.

3. Search — When You Need Context

Keyword search:

python3 {SKILL_DIR}/scripts/memory_store.py search "authentication middleware" --limit 10

Semantic search (finds conceptually related observations):

COWORK_MEM_DB=~/.claude/.cowork-mem/memory.db \
python3 {SKILL_DIR}/scripts/vector_search.py "how does auth work" --limit 8

Search returns compact results (truncated to 300 chars). Fetch full detail:

python3 {SKILL_DIR}/scripts/memory_store.py get obs_abc123 obs_def456

Chronological view:

python3 {SKILL_DIR}/scripts/memory_store.py timeline --hours 48

4. Session End — Summarize

When the user is wrapping up:

python3 {SKILL_DIR}/scripts/memory_store.py session-end \
  --summary "Implemented JWT auth middleware, set up PostgreSQL connection pool. Next: add rate limiting and write tests for auth endpoints."

Write the summary as a note to yourself tomorrow: what was accomplished, what's in progress, what's next.

Additional Skills

This plugin includes specialized skills for memory-aware workflows:

Skill	Use when...
mem-search	Searching memory for specific topics
knowledge-agent	Answering "why did we do X?" or "what's our approach to Y?"
smart-explore	Orienting to a project at session start
make-plan	Planning next steps grounded in past work
timeline-report	Getting a summary of what happened this week
do	Running any task with memory context loaded automatically

Maintenance Commands

Stats — see how much memory is stored:

python3 {SKILL_DIR}/scripts/memory_store.py stats

Compact — compress old observations into daily summaries:

python3 {SKILL_DIR}/scripts/memory_store.py compact --before-days 30

Export — dump everything as JSON or Markdown:

python3 {SKILL_DIR}/scripts/memory_store.py export --format md

Delete — remove specific observations:

python3 {SKILL_DIR}/scripts/memory_store.py delete obs_abc123

Behavior Guidelines

• Be proactive, not noisy. The hooks already do the work. Don't announce every save — just do it. Only surface recalled context when it changes your approach.

• Summarize, don't regurgitate. Synthesize retrieved context into what's relevant right now. "Last session we set up auth with JWT and decided on PostgreSQL" — not a bullet list of every observation.

• Quality over quantity. 5 well-written observations per session beats 50 low-signal ones. Each observation should be independently useful to someone reading it without other context.

• Use tags consistently. Lowercase, descriptive: architecture, bugfix, user-preference, api, deployment, etc.

• Search before deciding. When making architectural decisions or the user asks "didn't we already...", search memory first.

See references/REFERENCE.md for the complete command reference.

---

⭐ If this skill saved you time, star the repo — it helps other devs discover the marketplace.