Memory

All data lives in ~/Clawic/data/memory/ on the user's machine — plain markdown, no external services, no network requests. Configuration in ~/Clawic/data/memory/config.yaml (setup.md on first use, memory-template.md for file formats). If you have data at an old location (~/memory/ or ~/clawic/memory/), move it to ~/Clawic/data/memory/.

When To Use

• User says "remember this", "save this", "don't forget" about anything with lasting value
• Recall: "what did I tell you about X", "when did we decide Y", "who is Z" — search ~/Clawic/data/memory/ before answering "I don't know"
• A stored fact changed, turned out wrong, or contradicts what the user just said
• The user wants something forgotten, or asks what is stored about a subject
• Consolidating scattered notes, importing an existing vault, or sharing the store across devices and agents
• Recall degrades: misses, duplicates, stale answers, slow lookups as the store grows
• Not for: session-scoped context built-in memory already holds, secrets (Rule 9), note-taking apps (notes), journaling (journal), or study/spaced-repetition (learn, active-recall)
• Not for facts a domain skill already stores in its own ~/Clawic/data// (Rule 5): the pet fact goes to dog/cat, the household fact to family, the plant fact to garden, the code-style fact to coding

Quick Reference

Depth on demand: capture.md what to write and how to phrase it · recall.md search ladder, query expansion, proactive lookup · conflicts.md changed vs wrong facts, temporal validity · entities.md people, projects, aliases, merges · privacy.md secrets, sensitive subjects, deletion requests · migration.md importing and exporting · sync.md multi-device, git, multi-agent · scaling.md growth thresholds and when plain files stop being enough · sessions.md read/write protocol per session · maintenance.md cadences and integrity repair · layouts.md folder structures and split axes · commands.md operator toolkit · troubleshooting.md symptom→cause · memory-template.md file formats · setup.md first run.

Core Rules

1. Built-in memory is read-only territory, and sync runs one way. Never modify the runtime's MEMORY.md or workspace memory/ — the runtime owns them and may rewrite them, so your edits are lost or conflict. This skill reads them and copies into ~/Clawic/data/memory/sync/, reformatted, with the sync date recorded in sync/INDEX.md. Never the reverse, never automatic.

2. The user defines the structure. Create categories from their words, not a preset taxonomy. A category created before its first item rots empty and teaches the user the system is dead weight.

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

3. Write before you reply. Sequence: write the entry → update the category INDEX.md → then respond. The reply is disposable; the write is the durable part. A session that dies mid-reply then loses nothing.

4. Every entry carries a date and a source. YYYY-MM-DD plus one of stated (the user said it), observed (seen in a file or output), inferred (the agent concluded it). Undated facts can't be judged stale — "Alice works at Acme" means different things written last week and two years ago. Unsourced facts can't be trusted: an inference stored as a statement is the main way a memory store poisons itself, because Rule 8 lets a stated fact overrule an inferred one only if you can tell them apart.

5. One fact, one home — including homes outside this store. Store each fact in the file it is most about; everywhere else links to it (→ people/alice.md). Duplicated facts diverge silently — the copy you update is never the copy you find later. This applies across skills: when the fact's domain has its own Clawic store (~/Clawic/data/dog/, cat/, family/, couple/, garden/, kanban/, coding/, employee/), that store is the home and this one keeps at most a pointer line — "dog's diet → ~/Clawic/data/dog/". Writing "the dog is allergic to chicken" in both places is the silent fork this rule exists to prevent.

6. Every folder has an INDEX.md, capped at index_split_at (default 100). Past the cap, split into subcategories. Capacity = cap^depth: at the default, two levels hold 10,000 items, three hold 1,000,000, and every lookup stays two or three small reads instead of one giant scan. Every number below written as 100 is that default — read config.yaml before judging any index size. Archive indices are exempt (rarely read, off the hot path).

7. Keep entry files lean. An entry is loaded whole to answer one question, so its size is a tax on every question. Past entry_max_lines (default ~200), move the ## History bulk to {name}-history.md and keep the dossier short; the history file is opened only when someone asks about the past.

8. Changed facts supersede; wrong facts get deleted. A fact that became false (Alice left Acme) keeps its old line, dated, under History, with the new line on top — the timeline is itself information. A fact that was never true (she never worked there) is deleted outright: archived wrong facts resurface later as truth. Test: "was this true on the day it was written?" Yes → supersede. No → delete.

9. Never store secrets. These files are plaintext with no encryption. Decline passwords, API keys, tokens, and full card or account numbers; store a pointer instead — "API key lives in [their vault], rotated 2026-07".

Built-In Memory vs This Store

Built-in memory holds current context and works automatically. This store holds everything that grows. Parallel and complementary — never a replacement.

The same item can live in both — summary there, detail here, and the summary points here. When in doubt: does it grow over time, or does it need to be findable in a year? Then it belongs here.

Entry Anatomy

Every entry file, whatever the category, carries the same four things (full templates: memory-template.md):

# Alice Smith                                    <- display name, human-readable
**Keywords:** Ali, PM, product manager, Acme, alpha project    <- retrieval aliases
**Updated:** 2026-07-25                          <- freshness at a glance

## Facts
- 2026-07-25 · stated · Moved to Northwind as Head of Product
- 2026-03-02 · stated · Prefers async updates, no calls before 10:00

## History
- 2024-11-08 · stated · Joined Acme as PM   (superseded 2026-07-25)

• Filename is a stable slug (alice-smith.md), never the display name — renames break every inbound link (entities.md).
• One fact per line, dated and sourced (Rule 4). Lines, not paragraphs: a paragraph can't be superseded or deleted surgically.
• Keywords is the retrieval index, not decoration — see Finding Things.

Finding Things

cat ~/Clawic/data/memory/INDEX.md                 # which categories exist
grep -i "alpha" ~/Clawic/data/memory/*/INDEX.md   # which category holds it
cat ~/Clawic/data/memory/projects/alpha.md        # the answer

Vocabulary asymmetry is the reason recall misses: grep matches the words used at write time, recall arrives in today's words. Try at least 3 variants — the user's word, the formal name, the entity's canonical slug — before concluding absence, and when a miss is later resolved, add the missed term to that file's Keywords: line so the same search never misses twice (recall.md).

When Facts Change

Maintenance

Every session: anything durable said this session is written (Rule 3); anything unclear is in inbox/.

Weekly (or per maintenance_cadence): sort inbox/ into categories; update any INDEX touched during the week; archive items with terminal status (completed, cancelled, inactive).

Monthly: audit index sizes (wc -l ~/Clawic/data/memory/*/INDEX.md); split any category past index_split_at; sweep for stale facts by class; delete entries that are wrong. Repair procedures and the integrity checks: maintenance.md.

Output Gates

Before replying when the user shared something durable:

• Is it written to ~/Clawic/data/memory/ already? (Rule 3 — the write precedes the reply)
• Is the category INDEX.md row added or updated?
• Does the entry carry a date and a source marker? (Rule 4)

Before answering "I don't remember": did the full search ladder run with ≥3 keyword variants, including inbox/, sync/, and built-in memory?

Before storing: does it contain a credential (Rule 9) or fall under excluded_topics? → decline and say so once.

Before deleting: is this a wrong fact rather than an outdated one (Rule 8), and does delete_policy require confirmation first?

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/memory/config.yaml.

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Taxonomy: which categories exist and what belongs in each — affects Rule 2 and every capture routing decision
• Capture threshold: write everything said, or only explicit "remember this" — affects the durability test in capture.md
• Naming conventions: filename style, entity slug format, index columns — affects entities.md and memory-template.md
• Retrieval style: how much surrounding context comes back with an answer, and whether the agent volunteers related facts unasked — affects recall.md and sessions.md
• Privacy posture: which subjects need an explicit go-ahead, whether third-party personal details are stored at all — affects privacy.md
• Sync and versioning: cloud folder, git history, which agents share the store — affects sync.md
• Language: which language entries are written in when it differs from the conversation — affects every write

Traps

Where Experts Disagree

• Capture everything vs curate. Capture-everything survives only with real maintenance; curated stores stay fast but lose the fact nobody thought was important. Default: capture durable facts, inbox the ambiguous ones, and let the weekly sort be the curation step — the split lives in the capture threshold preference area.
• Folders vs flat plus tags. Flat + Keywords: scales fine for retrieval and badly for browsing; folders make a human able to read the store like a book. Default: folders, because the human decides whether the system is worth keeping. Escape hatch: one flat category with heavy keywords for domains with no natural taxonomy.
• Plain files vs a database. Grep over markdown stays honest, portable, and inspectable; an index or embedding store answers fuzzy questions plain grep can't. Default: files until >500 entries AND recall still misses after the Keywords fix (scaling.md) — the migration is one-way in practice.

Security & Privacy

Data location:

• All data in ~/Clawic/data/memory/ on the user's machine
• No external services, no network requests

This skill does NOT:

• Modify built-in agent memory (reads only, for one-way sync)
• Send data anywhere
• Store credentials — plaintext storage; secrets are declined (Rule 9)
• Write subjects listed in excluded_topics

Guardrails: deletion requests are honored in full and reported back (privacy.md); anything stored about third parties is limited to what the user needs recalled.

Related Skills

More Clawic skills, get them at https://clawic.com/skills/memory (install if the user confirms):

• notes — note-taking into apps like Obsidian, Notion, or Apple Notes; use it when the destination is an app, not a durable fact store
• journal — journaling practice, prompts, and reflection; use it for the entry the user writes, not the fact you extract from it
• learn — spaced repetition and study tracking; use it when the goal is knowing something by heart, not looking it up
• active-recall — retrieval practice as a study technique; use it when the user wants to be tested, not answered
• decide — decision-making patterns on top of the decisions/ category this store builds

Feedback

• If useful, star it: https://clawic.com/skills/memory
• Latest version: https://clawic.com/skills/memory

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/memory.