Memory Skill

Persistent knowledge storage with local RAG for agents.

Overview

The memory skill provides a three-tier storage system:

1. •SQLite Database - Fast queries, FTS5 search, vector embeddings
2. •Markdown Exports - Human-readable, git-trackable
3. •Archive - Low-relevance memories preserved for reference

Storage Locations (Default)

.agent/memory/
├── memory.db           # SQLite database (local runtime state; recommended gitignored)

memory/
├── exports/            # Markdown exports (shareable; git-trackable)
│   ├── architecture/
│   ├── implementation/
│   ├── issues/
│   └── patterns/
└── archive/            # Archived memory exports

Operations

Write Memory

Triggers:

• •"Remember this..."
• •"Save to memory..."
• •"Store this pattern..."

Flow:

1. •Extract: title, summary, tags, category
2. •Generate embedding for semantic search
3. •Insert into SQLite with FTS5 indexing
4. •Export to markdown for git tracking
5. •Confirm storage

Auto-categorization:

Example:

Remember: JWT auth uses 15-min access tokens with refresh tokens
Tags: auth, jwt, security

Search Memory (Hybrid RAG)

Triggers:

• •"What do we know about X?"
• •"Search memory for..."
• •"Find memories about..."
• •"Did we solve this before?"

Hybrid Search Pipeline:

Query → ┬→ FTS5 keyword search (BM25)        ─┐
        └→ Vector similarity (cosine)        ─┼→ Merge & Rank → Results
        ┌→ Tag/category filter               ─┘

Scoring:

• •keyword_score * 0.4
• •semantic_score * 0.4
• •relevance_score * 0.2 (importance, access count, links)

Syntax:

memory search: jwt authentication              # Hybrid search
memory search: jwt tag:security                # With tag filter
memory search: category:architecture           # Category filter
memory search: similar to mem-001              # Find similar
memory search: --include-archive               # Include archived

Update Memory

Trigger: "Update memory about X..."

Flow:

1. •Find memory by ID or search
2. •Apply changes to content
3. •Add entry to History section
4. •Re-generate embedding
5. •Update markdown export

Link Memory

Trigger: "Link memory X to Y"

Link types:

• •related - General relationship
• •supersedes - Newer replaces older
• •implements - Memory implements a story/bug

Example:

Link mem-001 to STORY-015
Link mem-003 supersedes mem-001

Archive Memory

Trigger: "Archive memory X" or auto-detected low relevance

Relevance factors (for auto-archive candidates):

• •Importance: low
• •Never accessed after creation
• •Not linked to other memories
• •Superseded by newer decision

Flow:

1. •Move export to archive/ directory
2. •Set archived=1 in database
3. •Remains searchable with --include-archive

List Memories

Trigger: "List memories" or "Show all memories"

Options:

list memories                      # All active, grouped by category
list memories category:arch        # Filter by category
list memories tag:security         # Filter by tag
list memories --include-archive    # Include archived

Memory Stats

Trigger: "Memory stats" or "Memory statistics"

Output:

• •Total memories (active/archived)
• •By category breakdown
• •Most accessed memories
• •Archive candidates (low relevance)
• •Database size

Auto-Integration

With Process Skill

Key decisions are auto-saved silently during development:

• •Architecture decisions
• •Pattern choices
• •Problem solutions
• •Configuration rationale

With Reviewer Skill

Recurring issues are auto-remembered:

• •Common bugs and their fixes
• •Security patterns
• •Code quality findings

Implementation Check

Before implementing, check: "Did we solve this before?"

• •Searches for similar problems
• •Returns relevant past solutions

Memory Entry Format

Database Schema

memories (id, title, summary, content, category, scope,
          importance, created_at, accessed_at, access_count,
          supersedes, archived, export_path)
memories_fts (title, summary, content)  -- FTS5 virtual table
memories_vec (memory_id, embedding)      -- 384-dim vectors
tags (memory_id, tag)
links (source_id, target_id, link_type)

Markdown Export

---
id: mem-001
title: JWT Authentication Pattern
tags: [auth, jwt, security]
category: architecture
importance: high
created: 2026-02-01T10:00:00Z
---

# JWT Authentication Pattern

## Summary
Use refresh tokens with 15-min access token expiry.

## Context
[Why this decision was made]

## Implementation
[Code examples, configuration]

## Related
- mem-002: Token Refresh Flow

## History
- 2026-02-01: Initial creation

Setup

Automatic (via ICC installers)

If npm is available during make install or .\install.ps1 install, dependencies are installed automatically.

Manual Setup (if needed)

# Linux/macOS
cd ~/.claude/skills/memory && npm install --production

# Windows PowerShell
cd $env:USERPROFILE\.claude\skills\memory
npm install --production

Dependencies

For CLI features (optional but recommended):

• •better-sqlite3 - SQLite with native bindings
• •@xenova/transformers - Local embedding generation

First use of embeddings downloads the model (~80MB) to ~/.cache/transformers/.

Fallback Behavior

If CLI/dependencies unavailable, the skill works via manual markdown:

1. •Write memories as markdown files in memory/exports/
2. •Search using Grep tool or file search
3. •All memory functionality remains available, just without hybrid RAG

Execution

Method 1: CLI (Recommended when Node.js available)

If the memory skill's dependencies are installed:

# Path to CLI (adjust for your installation)
MEMORY_CLI="$HOME/.claude/skills/memory/cli.js"  # Linux/macOS
# $env:USERPROFILE\.claude\skills\memory\cli.js   # Windows

# Check if CLI is available
node $MEMORY_CLI --help

# Write a memory
node $MEMORY_CLI write \
  --title "JWT Authentication" \
  --summary "Use 15-min access tokens with refresh tokens" \
  --tags "auth,jwt,security" \
  --category "architecture" \
  --importance "high"

# Search (hybrid: keyword + semantic)
node $MEMORY_CLI search "authentication tokens"

# Quick search (keyword only, faster)
node $MEMORY_CLI quick "jwt"

# List memories
node $MEMORY_CLI list --category architecture

# Get specific memory
node $MEMORY_CLI get mem-001

# Statistics
node $MEMORY_CLI stats

Method 2: Manual Markdown (Fallback)

When Node.js/dependencies unavailable, manage memories as markdown files directly:

Write:

mkdir -p memory/exports/architecture
cat > memory/exports/architecture/mem-001-jwt-auth.md << 'EOF'
---
id: mem-001
title: JWT Authentication Pattern
tags: [auth, jwt, security]
category: architecture
importance: high
created: 2026-02-07T10:00:00Z
---

# JWT Authentication Pattern

## Summary
Use 15-min access tokens with refresh tokens.

## Details
[Full description here]
EOF

Search:

# Keyword search in exports
grep -r "authentication" memory/exports/

List:

find memory/exports -name "*.md" -type f

Cross-Platform Notes

Cross-Platform

• •Windows/macOS/Linux supported
• •SQLite works everywhere
• •Markdown exports are universal
• •Model cached per-user (not per-project)