Memory

Infinite organized memory that complements your agent's built-in memory with unlimited categorized storage.

Security Scan

This is an instruction-only local memory system that consistently documents creating and managing a ~/memory/ folder for long-term organized storage and does not request credentials, installs, or network access — its requirements and instructions align with its stated purpose.

Purpose & Capability

Name/description match the content: the skill is a file-based 'infinite' memory system. It only requires file I/O in the user's home directory (~/memory/) and does not ask for unrelated binaries, credentials, or services.

Instruction Scope

SKILL.md instructs the agent to create, read, move, index, and search Markdown files under ~/memory/ and optionally to read built-in memory (MEMORY.md) for one-way sync. These operations are consistent with the purpose, but the skill does instruct the agent to write to the user's home directory and to read workspace built-in memory when syncing — the user should expect on-disk persistence of potentially sensitive data and explicit consent should be obtained before syncing built-in memory.

Install Mechanism

No install spec and no code files — instruction-only. This is lowest-risk from an installation perspective because nothing is downloaded or executed beyond normal shell commands if the agent runs them.

Credentials

No environment variables, credentials, or config paths are requested. The documented operations only use file paths under the user's home and optionally read the agent's built-in MEMORY.md when the user opts into sync, which is proportionate to the described functionality.

Persistence & Privilege

The skill persists data by writing files into ~/memory/ (intentional per spec). always is false and autonomous invocation is allowed (platform default). This combination is reasonable for a memory skill but increases blast radius if the agent is allowed to act autonomously — users should ensure they trust the agent to create persistent files.

Scan Findings in Context

[regex-scanner-no-findings] expected: Scanner had no code files to analyze; this is an instruction-only skill so absence of findings is expected.

Assessment

This skill is coherent and local-only, but before installing consider: (1) it will create and persist potentially sensitive text files in ~/memory/ — decide where you want them stored and whether to encrypt or back them up; (2) the agent may write entries immediately when users provide data, so confirm that behavior with end users; (3) syncing from built-in memory is one-way and must be explicitly enabled — do not enable sync unless you want copies of MEMORY.md content placed in ~/memory/; (4) because the agent can be invoked autonomously (platform default), only enable the skill for agents you trust to create and manage files on your behalf; (5) review/remove ~/memory/ if you later want to revoke the skill's data; and (6) if you have security policies about data-at-rest in user home directories, treat this skill like any other that writes persistent files and apply appropriate controls (permissions, encryption, audit).

Superpowered memory that never forgets.

Your agent has basic built-in memory. This skill adds infinite, perfectly organized memory for everything else — parallel and complementary, never conflicting.

How It Works

Built-in Agent Memory          This Skill (~/memory/)
┌─────────────────────┐        ┌─────────────────────────────┐
│ MEMORY.md           │        │ Infinite categorized storage │
│ memory/ (daily logs)│   +    │ Any structure you want       │
│ Basic recall        │        │ Perfect organization         │
└─────────────────────┘        └─────────────────────────────┘
         ↓                                  ↓
   Agent basics                    Everything else
   (works automatically)           (scales infinitely)

Not a replacement. Your agent's built-in memory keeps working. This adds a parallel system for unlimited, organized storage.

Setup

On first use, read setup.md to configure the memory system with the user. Key decisions:

1. What categories do they need?
2. Should we sync anything from built-in memory?
3. How do they want to find things?

When to Use

User needs organized long-term storage beyond basic agent memory: detailed project histories, extensive contact networks, decision logs, domain knowledge, collections, or any structured data that grows over time.

Architecture

Memory lives in ~/memory/ — a dedicated folder separate from built-in agent memory.

~/memory/
├── config.md              # System configuration
├── INDEX.md               # What's stored, where to find it
│
├── [user-defined]/        # Categories the user needs
│   ├── INDEX.md           # Category overview
│   └── {items}.md         # Individual entries
│
└── sync/                  # Optional: synced from built-in memory
    └── ...

The user defines the categories. Common examples:

• projects/ — detailed project context
• people/ — contact network with full context
• decisions/ — reasoning behind choices
• knowledge/ — domain expertise, reference material
• collections/ — books, recipes, anything they collect

See memory-template.md for all templates.

Quick Reference

Topic	File
First-time setup	setup.md
All templates	memory-template.md
Organization patterns	patterns.md
Problems & fixes	troubleshooting.md

---

Core Rules

1. Separate from Built-In Memory

This system lives in ~/memory/. Never modify:

• Agent's MEMORY.md (workspace root)
• Agent's memory/ folder (if it exists in workspace)

Parallel, not replacement. Both systems work together.

2. User Defines Structure

During setup, ask what they want to store. Create categories based on their needs:

They say...	Create
"I have many projects"	~/memory/projects/
"I meet lots of people"	~/memory/people/
"I want to track decisions"	~/memory/decisions/
"I'm learning [topic]"	~/memory/knowledge/[topic]/
"I collect [things]"	~/memory/collections/[things]/

No preset structure. Build what they need.

3. Every Category Has an Index

Each folder gets an INDEX.md that lists contents:

# Projects Index

| Name | Status | Updated | File |
|------|--------|---------|------|
| Alpha | Active | 2026-02 | alpha.md |
| Beta | Paused | 2026-01 | beta.md |

Total: 2 active, 5 archived

Indices stay small (<100 entries). When full, split into subcategories.

4. Write Immediately

When user shares important information:

1. Write to appropriate file in ~/memory/
2. Update the category INDEX.md
3. Then respond

Don't wait. Don't batch. Write immediately.

5. Search Then Navigate

To find information:

1. Ask first: "Is this in ~/memory/ or built-in memory?"
2. Search: grep or semantic search in ~/memory/
3. Navigate: INDEX.md → category → specific file

# Quick search
grep -r "keyword" ~/memory/

# Navigate
cat ~/memory/INDEX.md           # What categories exist?
cat ~/memory/projects/INDEX.md  # What projects?
cat ~/memory/projects/alpha.md  # Specific project

6. Sync from Built-In (Optional)

If user wants certain info copied from built-in memory:

~/memory/sync/
├── preferences.md    # Synced from built-in
└── decisions.md      # Synced from built-in

Sync is one-way: Built-in → this system. Never modify built-in.

7. Scale by Splitting

When a category grows large:

• INDEX.md > 100 entries → split into subcategories
• Create sub-INDEX.md for each subcategory
• Root INDEX.md points to subcategories

~/memory/projects/
├── INDEX.md           # "See active/, archived/"
├── active/
│   ├── INDEX.md       # 30 active projects
│   └── ...
└── archived/
    ├── INDEX.md       # 200 archived projects
    └── ...

---

What to Store Here (vs Built-In)

Store HERE (~/memory/)	Keep in BUILT-IN
Detailed project histories	Current project status
Full contact profiles	Key contacts quick-ref
All decision reasoning	Recent decisions
Domain knowledge bases	Quick facts
Collections, inventories	—
Anything that grows large	Summaries

Rule: Built-in for quick context. Here for depth and scale.

---

Finding Things

For Small Memory (<50 files)

# Grep is fast enough
grep -r "keyword" ~/memory/

For Large Memory (50+ files)

Navigate via indices:

1. ~/memory/INDEX.md → find category
2. ~/memory/{category}/INDEX.md → find item
3. ~/memory/{category}/{item}.md → read details

For Huge Memory (500+ files)

Use semantic search if available, or hierarchical indices:

~/memory/projects/INDEX.md → "web projects in web/"
~/memory/projects/web/INDEX.md → "alpha project"
~/memory/projects/web/alpha.md → details

---

Maintenance

Weekly (5 min)

• Update INDEX.md files if entries added
• Archive completed/inactive items

Monthly (15 min)

• Review category sizes
• Split large categories
• Remove outdated entries

When Memory is Slow

• Check INDEX.md sizes (keep <100 lines)
• Split big categories into subcategories
• Archive old content

---

Common Traps

• Modifying built-in memory → Never touch agent's MEMORY.md or workspace memory/. This system is parallel.

• No indices → Without INDEX.md, finding things requires searching all files. Always maintain indices.

• One giant category → 500 items in one folder is slow. Split into subcategories.

• Syncing everything → Don't copy all built-in memory. Only sync what needs organization here.

• Waiting to write → Write immediately when user shares info. Don't batch.

---

Security & Privacy

Data location:

• All data in ~/memory/ on user's machine
• No external services required
• No network requests

This skill does NOT:

• Access built-in agent memory (only reads if syncing)
• Send data anywhere
• Store credentials (never store secrets in memory)

---

Related Skills

Install with clawhub install <slug> if user confirms:

• decide - Decision tracking patterns
• escalate - When to involve humans
• learn - Adaptive learning

Feedback

• If useful: clawhub star memory
• Stay updated: clawhub sync