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 ICA installer flows)

If npm is available during ica install (CLI or dashboard-backed operations), 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

Permission-First Install Behavior

If better-sqlite3 is missing, explicitly ask the user for permission before installing:

1. •Explain why install is requested: better-sqlite3 is the Node.js SQLite binding used by the memory CLI's primary backend.
2. •Offer zero-extra-package fallback: if system sqlite3 CLI is available, memory persistence still works without npm install.
3. •Ask for approval before running install commands: cd <skill-home>/skills/memory && npm install --production

Do not run dependency installation silently.

Dependencies

For CLI features:

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

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

Why better-sqlite3 instead of "default sqlite"

• •SQLite itself is the database engine/file format.
• •better-sqlite3 is the Node.js driver that gives this JavaScript CLI direct, reliable DB access.
• •When better-sqlite3 is unavailable, the skill now falls back to the system sqlite3 CLI backend automatically (if present).

Fallback Behavior

If the primary backend is unavailable:

1. •Use sqlite3 CLI fallback automatically (when sqlite3 binary exists)
2. •If neither backend is available, use manual markdown workflow

Manual markdown mode:

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)
#
# Portable (Linux/macOS):
# - Prefer ICA_HOME if set (works for custom installs like ~/.ica)
# - Fallback to common agent homes (~/.codex, ~/.claude)
MEMORY_CLI=""
for d in "${ICA_HOME:-}" "$HOME/.codex" "$HOME/.claude"; do
  if [ -n "$d" ] && [ -f "$d/skills/memory/cli.js" ]; then
    MEMORY_CLI="$d/skills/memory/cli.js"
    break
  fi
done
#
# Windows PowerShell equivalent (example):
# $MemoryCli = @($env:ICA_HOME, "$env:USERPROFILE\\.codex", "$env:USERPROFILE\\.claude") |
#   Where-Object { $_ -and (Test-Path (Join-Path $_ "skills\\memory\\cli.js")) } |
#   ForEach-Object { Join-Path $_ "skills\\memory\\cli.js" } |
#   Select-Object -First 1

# 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

# Backend status (better-sqlite3 vs sqlite3 CLI fallback)
node "$MEMORY_CLI" backend

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)