/engramory

name: engramory
description: >-
  Curated, file-based long-term memory for an AI agent. Use this skill (1) at the
  start of a task or when resuming unfinished work to recall via the memory index,
  (2) during a task to save durable user, feedback, project, or reference facts,
  (3) when a task finishes, to run the completion checkpoint — promote what is
  durable, retire what was only transient, and write nothing when nothing qualifies
  (an empty checkpoint still has to be decided) — and (4) before compacting,
  clearing context, or opening a fresh thread to sync the current goal, state,
  decisions, constraints, blockers, and next step.
  A turn that starts no work — a greeting, an acknowledgement — is not a task and
  needs none of this, but never judge that by length: a one-word reply continuing
  work underway inherits that task.
  Each memory is one small markdown file; a single always-loaded index (MEMORY.md)
  lists them. Works on any agent host that can read and write local files.

Engramory — curated file-based long-term memory

Engramory is a *discipline*, not a database. Memory is a directory of small, human-readable markdown files plus one index. There is no vector store, no embeddings, no server. You (the agent) read the index, open the files that matter, and keep the store clean over time.

This file is self-contained: it defines the full storage layout, the recall protocol, the write protocol, and the curation rules. A host that loads this file as standing instructions and can read/write files can use Engramory even if it has no built-in memory feature.

---

0. Where memory lives

Memory lives under a single root directory, `<MEMORY_ROOT>`, that the **user can see, open, and audit**. Human-readability is the whole point — never hide the store somewhere the user will not look.

This directory is the **one canonical Engramory store** for both durable memory and resumable project state. Do not create a second "handoff" memory type or a parallel handoff store: unfinished-task continuity belongs in a `project` note and follows the same index, dedup, correction, and retirement rules.

• Default: a `memory/` directory the user configures (e.g. inside their notes

folder, or a `memory/` folder at the root of the active project).

• It MUST be configurable; never hard-code an absolute path in the skill.
• If `<MEMORY_ROOT>` lives inside a git repository, it MUST be git-ignored —

memories routinely contain machine-local, sensitive but non-credential detail (server IPs, ssh paths, serial numbers). Confirm `.gitignore` covers it before writing there. (Credential *values* never belong in memory at all — see §5.)

• On a host whose native memory is a **plain directory of files you control**

(e.g. Claude Code), `<MEMORY_ROOT>` may be that directory, and Engramory layers its conventions on top. But if the host **manages** its own memory — writing, rewriting, or freezing files through its own manager (Codex's native Memories, OpenClaw's auto-written memory, Hermes's managed files) — point Engramory at a **separate folder you control**. Two writers with different house styles will fight over the same files. Check `PORTING.md` and the adapter README for the host before reusing its directory.

Layout:

<MEMORY_ROOT>/
  MEMORY.md            # the index — loaded every session, pointers only
  <slug>.md            # one memory = one file = one fact
  <slug>.md
  archive/             # retired / superseded memories (kept, but out of the index)

---

1. The unit: one file = one fact

Every memory is its own markdown file. Normally one file holds exactly **one** durable fact or agreement. If you are tempted to combine unrelated facts, make separate files.

The narrow exception is **at most one** live `project` note for one unfinished task: its goal, current status, decisions, constraints, blockers, and next step form one cohesive continuity unit and are useful together. Update that note in place; never create a series of snapshot files, and retire its transient state when the task completes.

File frontmatter (a restricted `key: value` subset — not full YAML; no multi-line values or lists, parsed by a zero-dependency reader). A value is either bare, or wrapped in ONE matching quote pair; a quote inside that pair must be backslash-escaped, and a bare value is never de-quoted (so a trailing `"` in prose survives intact):

---
name: <kebab-case-slug>          # matches the filename, used as the [[link]] target
description: <one line>          # used to judge relevance during recall — write it well
type: user | feedback | project | reference
scope: global | repo             # optional — does this still hold in another repo? (§2.1)
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

<the fact, in plain prose>

The `description` is the single most important field: recall works by you reading these one-liners in the index and deciding what to open. A vague description makes a memory effectively invisible. Write it as the hook that would make *future you* open the file.

Link related memories in the body with `[[other-slug]]`. A link to a slug that does not exist yet is fine — it marks something worth writing later.

---

2. The four types

The type tells you how to treat the memory: whether it carries an action, whether it goes stale, and when to recall it.

`user` — who the user is

Stable facts about the person: role, expertise, durable preferences, identity. > *Example:* "User is the founder of the company and its lead backend engineer." > (A *reply-style* preference like "answer in Chinese" is `feedback`, not `user` — > see the confusable pair below.)

`feedback` — how you should behave

Guidance and corrections about *how you do your work*. This is procedural memory — the rarest and most valuable type. It MUST carry two lines:

• **Why:** the reason behind the rule (so you know when an exception is allowed)
• **How to apply:** the concret