Memory System

OpenClacky has a built-in long-term memory system. After sufficiently complex sessions, the agent automatically extracts and saves key knowledge so it's available in future sessions — without you having to repeat context.

How It Works

At the end of a session (when the task had enough back-and-forth), the agent:

1. Reviews what was discussed
2. Decides which knowledge is worth persisting
3. Creates or updates files in ~/.clacky/memories/
4. Merges new information with existing memories intelligently

This happens automatically — you don't need to trigger it.

Memory Files

Memories live in ~/.clacky/memories/ as Markdown files. Each file covers a topic:

~/.clacky/memories/
  openclacky-product.md    # product decisions, architecture
  my-project.md            # project-specific context
  user-preferences.md      # how you like things done

Each file has a YAML header:

---
topic: my-project
description: Rails app architecture, conventions, key decisions
updated_at: 2026-03-17
---

# My Project

## Architecture
...

The description field is how the agent decides which files to load when recalling — it's scanned without loading the full file.

Recalling Memories

The recall-memory built-in skill retrieves relevant memories on demand. It's invoked automatically when the agent encounters a topic it has prior context on.

You can also trigger it explicitly:

recall what we decided about the auth system

The skill reads only relevant files (matched by topic/description), not all memories — keeping it fast and focused.

What Gets Remembered

The agent prioritizes:

• Key decisions — architecture choices, trade-offs, why something was done a certain way
• Project context — tech stack, patterns, domain model
• User preferences — how you like code structured, communication style
• Corrections — things the agent got wrong that were corrected

It does not store:
- Step-by-step task logs
- Trivial exchanges
- Content that's already in .clackyrules

Managing Memories

Memory files are plain Markdown — you can read, edit, or delete them directly:

ls ~/.clacky/memories/
cat ~/.clacky/memories/my-project.md
rm ~/.clacky/memories/outdated-topic.md

To clear all memories:

rm -rf ~/.clacky/memories/

Memory vs. .clackyrules

Use .clackyrules for project-specific instructions. Memories are for cross-session knowledge the agent builds up over time.