# Memory

> Activate when user wants to save knowledge, search past decisions, or manage persistent memories. Handles architecture patterns, implementation logic, issues/fixes, and past implementations. Uses local SQLite + FTS5 + vector embeddings for fast hybrid search. Supports write, search, update, archive, and list operations.

- Skill: `intelligentcode-ai/memory` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add intelligentcode-ai/memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/intelligentcode-ai/memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: intelligentcode-ai (https://skillmd.com/u/intelligentcode-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/intelligentcode-ai/memory

---


# 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:**
| Keywords | Category |
|----------|----------|
| design, pattern, structure, architecture | architecture |
| code, function, module, implement | implementation |
| bug, fix, error, problem, issue | issues |
| approach, solution, method, technique | patterns |

**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
```sql
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
```markdown
---
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)
```bash
# 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:

```bash
# 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:**
```bash
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:**
```bash
# Keyword search in exports
grep -r "authentication" memory/exports/
```

**List:**
```bash
find memory/exports -name "*.md" -type f
```

### Cross-Platform Notes

| Platform | CLI Available | Fallback |
|----------|---------------|----------|
| Linux | Yes (if Node.js installed) | Manual markdown |
| macOS | Yes (if Node.js installed) | Manual markdown |
| Windows | Yes (if Node.js installed) | Manual markdown |
| Codex/GPT | No | Manual markdown |
| Cursor | Depends on setup | Manual markdown |

## Cross-Platform

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