sick-memory

name	sick-memory
description	Use this skill when the user wants to manage persistent memory for AI coding agents with centralized storage, git-based scoping, and worktree support, or integrate memory systems with Claude Code, OpenCode, or other AI agents. Agents should learn this skill to understand how to use sick-memory for context persistence across sessions.

Sick-Memory Plugin

File-based memory system for AI coding agents with centralized storage, git-based scoping, and worktree support - persistent knowledge storage across sessions using markdown files with YAML frontmatter, inspired by Claude Code's memory system.

Agent Usage Instructions

As an AI agent, use sick-memory to maintain context across sessions and remember important project information:

When to Use Sick-Memory

• Session Start: Recall relevant project context before starting work
• Important Discoveries: Remember key findings, decisions, or technical insights
• Project Patterns: Store architectural decisions, coding patterns, or conventions
• Troubleshooting: Remember solutions to problems for future reference
• Context Switching: Quickly recall project context when returning to work

Core Workflow

1. At session start: sc sick-memory memory recall "project context" --json
2. During work: sc sick-memory memory remember "Key finding: X requires Y approach" --type project
3. When stuck: sc sick-memory memory recall "previous solutions" --json
4. Before completion: sc sick-memory memory remember "Implementation completed: feature X" --type project

Commands

SuperCLI Plugin Commands (Recommended)

• sc sick-memory init — Initialize memory system for current project
• sc sick-memory memory remember "<content>" — Add a memory to the project (CORRECT SYNTAX)
• sc sick-memory memory recall [query] — Retrieve relevant memories
• sc sick-memory memory list — List all memories in the project
• sc sick-memory memory status — Show memory system status
• sc sick-memory config show — Show configuration and storage location
• sc sick-memory bridge generate <agent> — Generate agent-specific integration (claude-code, opencode, copilot)
• sc sick-memory edit run <id> <content> — Edit a memory by ID (non-interactive)
• sc sick-memory delete run <id> — Delete a memory by ID

CRITICAL: The correct command structure is sc <namespace> <resource> <action>, not sc <namespace> <action>. For example:

• Correct: sc sick-memory memory remember "content"
• Incorrect: sc sick-memory remember "content"

Quick Access via /sm Shorthand

• /sm init — Initialize memory system
• /sm remember "<content>" — Add a memory
• /sm recall [query] — Retrieve memories
• /sm list — List all memories
• /sm status — Show system status
• /sm config show — Show configuration

Direct CLI Commands (Fallback)

• sick-memory init — Initialize memory system
• sick-memory remember "<content>" — Add a memory
• sick-memory recall [query] — Retrieve memories
• sick-memory list — List all memories
• sick-memory status — Show system status
• sick-memory config — Show configuration
• sick-memory edit <id> <content> — Edit a memory (non-interactive)
• sick-memory delete <id> — Delete a memory

JSON Output (For Programmatic Use)

Add --json flag to any command for structured output:

• sc sick-memory recall "query" --json — Returns structured memory data
• sc sick-memory status --json — Returns system status in JSON
• sc sick-memory list --json — Returns memory list in JSON
• sc sick-memory edit run <id> <content> --json — Returns edit confirmation in JSON
• sc sick-memory delete run <id> --json — Returns delete confirmation in JSON

Usage Examples

Agent-Focused Examples

• "Initialize memory for this project" → sc sick-memory init
• "Remember that we use real database instances in tests" → sc sick-memory memory remember "Use real database instances in tests, not mocks" --type project
• "Recall memories about database testing" → sc sick-memory memory recall "database testing" --json
• "List all project memories" → sc sick-memory memory list --json
• "Show configuration and storage location" → sc sick-memory config show
• "Generate Claude Code bridge for this project" → sc sick-memory bridge generate claude-code
• "Check memory system status" → sc sick-memory memory status --json
• "Update memory 1779456013 with new content" → sc sick-memory edit run 1779456013 "Updated content here" --json
• "Delete memory 1779456013" → sc sick-memory delete run 1779456013 --json

Quick Examples

# Session start - recall context
sc sick-memory memory recall "project context" --json

# Remember important finding
sc sick-memory memory remember "Authentication uses JWT tokens with 24h expiration" --type project

# Get system status
sc sick-memory memory status --json

# List all memories
sc sick-memory memory list --json

# Update existing memory (non-interactive)
sc sick-memory edit run 1779456013 "Updated content here" --json

# Delete memory
sc sick-memory delete run 1779456013 --json

# Using shorthand
/sm remember "API rate limit: 1000 requests per minute"
/sm recall "rate limit"

Installation

cd ~/ai/sick-memory
go build -o sick-memory .
cp sick-memory ~/.local/bin/

The supercli plugin handles installation automatically when using sc plugins install.

Centralized Storage

Sick-memory uses centralized storage with git-based scoping:

• Storage Location: ~/.sick-memory/projects/<sanitized-git-root>/memory/
• Git-based Scoping: Memory is scoped to git repository root
• Worktree Support: All git worktrees share the same memory directory
• Fallback: Uses local .sick-memory/ directory if not in a git repository

Global Configuration

Global configuration is stored in ~/.sick-memory/config.json:

• Default Memory Type: Default memory type (user, feedback, project, reference)
• Max Memory Size: Maximum memory file size in bytes
• Auto Index: Whether to automatically update memory index

Examples

# Show configuration and storage location
sc sick-memory config show

# Initialize memory system (uses centralized storage if in git repo)
sc sick-memory init

# Add a memory
sc sick-memory memory remember "Use real database instances in tests, not mocks"

# Using shorthand
/sm remember "Integration tests must hit real DB"

# Recall memories
sc sick-memory memory recall "database" --json

# List all memories
sc sick-memory memory list --json

# Check status
sc sick-memory memory status --json

# Generate Claude Code integration
sc sick-memory bridge generate claude-code

Key Features

• Centralized storage: All memories stored in ~/.sick-memory/ with git-based project scoping
• Git-based scoping: Memory automatically scoped to git repository root
• Worktree support: All git worktrees of the same repository share memory directory
• Global configuration: Centralized config file for user preferences
• File-based storage: Markdown files with YAML frontmatter for human readability
• Agent-agnostic: Works with Claude Code, OpenCode, Copilot, and other AI agents
• JSON output: Machine-readable output for agent integration
• Bridge commands: Generate agent-specific configurations automatically
• Zero infrastructure: No database or server required, works offline

Memory Types

The system supports four memory types (following Claude Code's taxonomy):

• user: Information about the person (role, goals, expertise)
• feedback: Corrections and confirmations about work approach
• project: Ongoing work context (who, what, why, when)
• reference: External system pointers (URLs, dashboard links)

Integration with AI Agents

Claude Code

sc sick-memory bridge generate claude-code

Creates .claude/CLAUDE.md with memory loading instructions and centralized storage information.

OpenCode

sc sick-memory bridge generate opencode

Creates .opencode/memory.json with OpenCode configuration.

Copilot

sc sick-memory bridge generate copilot

Creates .copilot/settings.json with Copilot configuration.

Caveats & Pitfalls

Plan Content Before Saving

There is no append or patch — edit replaces the entire content. If you save incomplete content, you must re-supply the full corrected text. Always construct the full content string before calling remember.

Always Use sc sick-memory Over Raw Binary

The raw sick-memory binary may open vim interactively for edit commands. The supercli plugin (sc sick-memory edit run) handles argument passing correctly and stays non-interactive.

Edit/Delete May Not Be Available in Older Binaries

Check the binary version (sick-memory --version). Edit/delete support was added later — verify with sick-memory --help before relying on them.

Delete May Fail Silently for Some IDs

sick-memory list reports a cached index. A memory shown in the list may already be deleted from disk. If sc sick-memory delete run <id> returns an integration error, check the filesystem directly at ~/.sick-memory/projects/<sanitized-git-root>/memory/.

sc Command Structure for Edit/Delete

• Edit: sc sick-memory edit run <id> "<content>" — content is a positional arg, not a flag
• Delete: sc sick-memory delete run <id> — requires the run action subcommand
• Use --json flag for machine-readable confirmation

Correct SuperCLI Command Structure

The supercli plugin follows the pattern sc <namespace> <resource> <action>:

• Remember: sc sick-memory memory remember "content" (NOT sc sick-memory remember "content")
• Recall: sc sick-memory memory recall "query" (NOT sc sick-memory recall "query")
• List: sc sick-memory memory list (NOT sc sick-memory list)
• Status: sc sick-memory memory status (NOT sc sick-memory status)

This is because the plugin.json defines namespace=sick-memory, resource=memory, action=remember/recall/list/status.

No Multi-Line Content from CLI

Content must be passed as a single CLI argument. For long content, construct it in a script or use sc sick-memory edit run with a heredoc-style content string. Escaping special characters (quotes, newlines) is the caller's responsibility.

YAML Frontmatter Is Auto-Generated

You cannot independently set name, description, type, or created fields. These are inferred from the content string and the --type option. The first line of content becomes the description field.

sick-memory list May Return Stale Index

The list command returns cached filenames. If a file was removed from disk externally (e.g., rm or a crash), it may still appear in list output. Always cross-reference with the filesystem if unsure.

Search Bugs (Fixed in v0.1.0)

The following bugs were identified and fixed in the binary (source at ~/ai/sick-memory/):

• TF-IDF negative scores for common terms: DocFreq was counting total occurrences instead of unique documents, making IDF negative when df > DocCount. Fixed by tracking per-document deduplication with a seen set.
• --json flag leaked into query: sick-memory recall <query> --json included --json in the search string. Fixed by filtering flags from os.Args[2:] in handleRecall.
• Search index not cached on recall: loadSearchIndex built the index from scratch every time but never saved it. Fixed by calling saveSearchIndex after building in loadSearchIndex.
• Multi-word queries failed for non-exact substrings: Queries like "UI design" didn't match content containing "UI/Design". Fixed by adding a word-overlap fallback that scores by individual keyword substring presence.

Command Structure

• sc sick-memory memory recall <query> --json — via sc plugin, query as positional arg (CORRECT)
• sc sick-memory memory recall --query <query> --json — via sc plugin, query as named flag (CORRECT)
• sick-memory recall <query> — direct binary call
• sick-memory recall (no query) — returns all memories, works with --json
• If search index is stale, delete search_index.json manually to force rebuild

IMPORTANT: The correct supercli pattern is sc <namespace> <resource> <action>, not sc <namespace> <action>. Always include the memory resource when using memory commands.

Learning This Skill

Agents can learn this skill by using:

sc skills teach sick-memory:quickstart

Or simply:

sc skills get sick-memory

This provides complete guidance for using sick-memory in any agent session.