Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jasonkneen/openclicky/llms.txt

Use this file to discover all available pages before exploring further.

OpenClicky is designed to remember. Between sessions, across reboots, and across different agent tasks, Clicky maintains a set of local files that act as durable working memory. There are no accounts, no cloud sync, and no server-side storage of your context: everything lives in ~/Library/Application Support/OpenClicky/, owned by you.

​
Where Data Lives

All persistent context is rooted under OpenClicky’s Codex home directory: 
~/Library/Application Support/OpenClicky/
└── CodexHome/
    ├── SOUL.md                        # OpenClicky's persona and operating identity
    ├── memory.md                      # Durable user/project context
    ├── OpenClickyModelInstructions.md # Agent system instructions
    ├── OpenClickyRuntimeMap.md        # Exact paths for all OpenClicky storage
    ├── OpenClickyBundledSkills/       # Built-in skill SKILL.md files
    ├── OpenClickyLearnedSkills/       # User-specific learned skills
    ├── OpenClickyBundledWikiSeed/     # Bundled wiki markdown articles
    ├── archives/                      # Archived previous versions of memory/skills
    │   └── memory/                    # Archived memory.md snapshots
    ├── memories/                      # Per-event memory entries (supplementary)
    ├── sessions/                      # Agent session transcripts
    └── pets/                          # Clicky pet data (if any)
The CodexHomeManager class manages this layout, creating directories on first launch and seeding bundled content from the app bundle.

​
memory.md: Durable Context

memory.md is the agent’s persistent long-term memory. It is a plain Markdown file that accumulates stable facts about you, your projects, your preferences, and past task outcomes. Every agent task reads it before doing any work and updates it when new durable context is learned.

​
What Gets Stored in Memory

User preferences

Code style choices, preferred tools, communication preferences, language preferences. Things that are stable across projects.

Project facts

Project names, repo locations, tech stack, key conventions. The context Clicky needs to work intelligently in your environment.

Task outcomes

What was built, what decisions were made, what didn’t work. Durable summaries so the agent doesn’t repeat completed work.

File locations

Where important files and configs live. Clicky notes these so future tasks don’t need to search from scratch.
Memory is kept concise and curated — not a raw log. The agent appends structured entries with a timestamp and trims entries that are no longer actionable.

​
The Memory Drawer

The Memory Drawer is a 320 pt slide-in panel accessible from the HUD and main notch panel. It shows:
  • The current content of memory.md (up to 6,000 characters, rendered as plain text)
  • A list of memory files in Codex home
  • Sessions that reference memory (conversations containing “memory”, “remember”, or “memo”)
  • A compose field to manually add entries: type a note, tap the + button, and appendPersistentMemoryEvent writes it to memory.md immediately
// Manual memory addition from MemoryDrawerView
try companion.codexHomeManager.appendPersistentMemoryEvent(
    userRequest: "(manual add via memory drawer)",
    agentResponse: trimmed
)
The memory file has a soft cap of 120,000 bytes. When it approaches this limit, the agent is expected to archive older entries rather than blindly truncate.

​
The Archive-First Rule

Before replacing, pruning, or superseding any OpenClicky memory entry, skill, prompt, runtime note, config, or log-derived artifact, the agent must archive the previous version under the archives path from OpenClickyRuntimeMap.md. Old versions are never deleted unless the user explicitly asks for destructive deletion.
This rule is enforced in the agent system instructions:
“Archive-first is mandatory. When replacing, optimizing, pruning, or superseding OpenClicky memory, skills, runtime notes, prompts, config, or log-derived artifacts, copy or move the old version into archives/ first. Do not delete old artifacts unless the user explicitly asks for deletion and understands it is destructive.”
Archived memory snapshots live at: 
~/Library/Application Support/OpenClicky/CodexHome/archives/memory/

​
OpenClickyRuntimeMap.md: The Path Map

OpenClickyRuntimeMap.md is a machine-readable file that lists the exact local paths for every OpenClicky storage location: logs, memory, skills, widget state, sessions, config, and review comments. When an agent needs to find where something is stored, it reads this file first rather than guessing. 
- memory:       ~/Library/Application Support/OpenClicky/CodexHome/memory.md
- skills:       ~/Library/Application Support/OpenClicky/CodexHome/OpenClickyLearnedSkills/
- sessions:     ~/Library/Application Support/OpenClicky/CodexHome/sessions/
- archives:     ~/Library/Application Support/OpenClicky/CodexHome/archives/
- logs:         ~/Library/Application Support/OpenClicky/logs/
- widget state: ~/Library/Application Support/OpenClicky/widget-snapshot.json
- review notes: ~/Library/Application Support/OpenClicky/logs/agent-review-comments.md
If you ask Clicky “where does OpenClicky store its logs?”, it reads OpenClickyRuntimeMap.md and answers with exact paths.

​
The Local Wiki

OpenClicky includes a local Markdown wiki seeded from OpenClickyBundledWikiSeed/ — a directory of .md files bundled with the app. The wiki is managed by the WikiManager module in the OpenClickyCore package.

​
WikiManager Structure

The WikiManager.Index aggregates two kinds of entries:

Articles

General reference articles seeded from OpenClickyBundledWikiSeed/. Each article has a relativePath, title, body, and optional aliases for alternative search terms (declared with also: term1, term2 in the article body).

Skills

Capability definitions loaded from OpenClickyBundledSkills/. Each skill is a directory containing a SKILL.md file. The skill’s identifier is its directory name; title, summary, and body are parsed from frontmatter and headings.
// WikiManager.Index fields
public struct Index: Equatable {
    public var articles: [Article]
    public var skills: [Skill]
}

// Article fields
public struct Article: Identifiable {
    public var relativePath: String
    public var title: String
    public var body: String
    public var aliases: [String]
}

// Skill fields
public struct Skill: Identifiable {
    public var identifier: String
    public var title: String
    public var summary: String
    public var body: String
}
The index is loaded at startup from the app bundle’s resource directory. If a OpenClickyBundledWikiSeed/ folder is present in the bundle’s resources root, the index loads from there; otherwise it falls back to a source resources URL for development builds.

​
Searching the Wiki

WikiManager.Index provides article(containingTitle:) for case-insensitive substring matching across article titles and aliases: 
// Find an article by title or alias
let article = wikiIndex.article(containingTitle: "screen control")
The wiki viewer (WikiViewerEntry) merges articles and skills into a single alphabetically sorted list, each tagged with a kind (.article or .skill) and searchable via a combined searchableText field.

​
Learned Skills

Learned skills are user-specific workflow definitions that the agent creates and updates over time. They live under: 
~/Library/Application Support/OpenClicky/CodexHome/OpenClickyLearnedSkills/
Each learned skill is a named subdirectory containing a SKILL.md file: 
OpenClickyLearnedSkills/
├── weekly-report/
│   └── SKILL.md
├── deploy-to-vercel/
│   └── SKILL.md
└── gmail-triage/
    └── SKILL.md
The SKILL.md file uses frontmatter for metadata and Markdown for the skill body: 
---
name: Weekly Report
description: Generate a weekly Git activity and open-issues report
---

# Weekly Report

Triggers: "weekly report", "project summary", "what did we ship"

Steps:
1. Run `git log --oneline --since=1.week` in the project root
2. List open GitHub issues via Composio MCP
3. Write summary to ~/Documents/reports/
The agent is instructed to use curated, specific names for learned skills — not generic workflow_* names. Skills should have concrete trigger descriptions so the agent can recognise when a repeated workflow applies. The agent does not announce skill creation in its responses unless you specifically ask about skills.

​
Archive Before Optimising

When the agent improves an existing learned skill:
  1. The old SKILL.md is copied to archives/ with a timestamped path
  2. The improved SKILL.md is written in place
This ensures no skill knowledge is ever silently lost.

​
How Agents Interact With Memory

1

Read at task start

Every agent task begins by reading SOUL.md (persona) and memory.md (durable context). The agent treats these as authoritative ground truth — not as suggestions.
2

Consult the runtime map

If the task involves OpenClicky’s own storage (logs, memory, skills, widget state), the agent reads OpenClickyRuntimeMap.md for exact paths.
3

Work on the task

The agent executes the task using tools, skills, and integrations. Intermediate results and command output appear in the HUD transcript.
4

Update memory

If new durable context was learned — a project fact, a user preference, a task outcome — the agent appends it to memory.md before finishing.
5

Archive superseded content

Any content replaced during the task (skills, memory entries, config) is archived first.
The Memory Drawer lets you review and manually add to memory at any time, without needing to start an agent session.

Build docs developers (and LLMs) love

Get started for freeTalk to us