kortix-memory

How to read, write, and curate workspace memory in `memory/` — the workspace brain. Load this skill whenever you (or a scheduled memory curator) need to add, update, or reorganize what this workspace

SKILL.md

GitHub
<skill name="kortix-memory"> <overview> Every Kortix workspace has a **workspace brain** at `memory/` — a folder of curated markdown files describing what this workspace is, which connections it uses, the conventions the team works by, and the decisions worth not re-litigating.

Read and edit the files under memory/ with the file tools (read, write, edit, bash). A workspace that keeps its brain somewhere else (an older layout, .kortix/memory/) works the same way at that path. The memory tool that edited this folder is retired (2026-10-30): a workspace that ejected it into tools/memory.ts keeps its own copy.

MEMORY.md is the index. Memory is not auto-injected into the prompt — the memory protocol is: at the start of a task, read memory/MEMORY.md (kortix files cat memory/MEMORY.md, no clone needed) to recover prior context, then read the sub-files (overview.md, connections.md, etc.) the index points at when they're relevant. Record anything durable as you go — your context window may reset at any time, so what isn't written to memory/ is lost. /workspace starts empty: to edit memory, run kortix workspaces clone (it clones the repository onto your session branch), edit memory/ in the clone, commit, push, and open a change request (kortix cr open).

Memory is continuously CRUD'd:

  • Agents curate memory as they work. They add a durable fact when they find it, update a stale file, and delete a wrong one.
  • A new workspace has no scheduled curator. A workspace may add one: an agent that a cron trigger runs, which surveys recent activity and curates the folder (see <curator> below).
  • Both consult this skill for the rubric.

Memory is team-shared: it lives in the repo, every session sees the same content. Edits land on main only via a Kortix change request — never by pushing directly. </overview>

<when-to-load> Load this skill when you:
  • Discover a workspace convention, connection detail, decision, or workaround that should outlast this session
  • Notice the workspace brain is out of date or contradicts current code
  • Are a scheduled curator agent running its memory pass
  • Want to know if something is worth writing down (use the rubric below)
  • Need to add, rename, split, or delete a memory file
  • Want to know how memory edits reach main

Skip this skill for one-off questions about operating code. Workspace memory is about durable knowledge, not session state. </when-to-load>

<file-layout> A new workspace has `memory/MEMORY.md` only. The usual sub-files:
memory/
├── MEMORY.md           Index. `view` this first. One line per sub-file.
├── overview.md         What this project IS — purpose, shape, stakeholders.
├── connections.md      Third parties, MCP servers, channels, and connectors.
├── conventions.md      Coding patterns, naming, do / don't, style decisions.
└── decisions.md        Architectural and business decisions worth not re-debating.

Add new files freely when a topic deserves its own page (one topic per file, kebab-case filename). Always keep MEMORY.md in sync — one line per sub-file, format:

- [filename.md](filename.md) — one-line hook of what's inside

Don't move content out of MEMORY.md if it's a single line that already lives in the index — keep that one line. Sub-files exist when there's enough depth to warrant a click. </file-layout>

<rubric>

What to remember (KEEP)

  • The workspace's purpose — what we're building, for whom, and the one-sentence pitch.
  • Architecture-level decisions — why we use X over Y, which service owns what, the data flow.
  • Connection details — which third parties / MCP servers / channels are wired, what credentials they need, how they're scoped.
  • Conventions — naming, code style, branching, review norms — the stuff that's de facto across the codebase but not stated.
  • Workarounds and quirks — known env issues, ordering constraints, flaky dependencies, gotchas that bit us once.
  • Ops runbooks — how to deploy, how to roll back, how to debug the thing that breaks every quarter.
  • Glossary — domain terms specific to this workspace that an outsider wouldn't know.
  • People & ownership (optional) — who owns which surface, how to reach them, what they care about.

What NOT to remember (DROP)

  • One user's personal preferences — those are not workspace memory. They go in that user's own memory, /drives/me/Memory (the kortix-user-memory skill).
  • Facts derivable from the repo layout, file names, or git log.
  • One-off task state that won't matter next week.
  • Anything that's already in kortix.yaml, AGENTS.md, or a SKILL.md.
  • Secrets, tokens, API keys, PII — those live in the Kortix Secrets Manager, never in memory files.
  • Speculation about future plans. Memory describes what is, not what might be.

Style for entries

  • Plain prose with short sentences.
  • State facts, not narratives — "The web app talks to Supabase Postgres for auth" beats "We decided to use Supabase…".
  • Cite file paths when the fact maps to code: path/file.ts:120.
  • Date hard-to-verify facts in YYYY-MM-DD so readers can judge staleness.
  • Prefer editing existing entries over piling new ones on. A bloated file is worse than a tight one.
</rubric> <writing>

Editing memory

Read memory without a clone: kortix files cat memory/MEMORY.md and kortix files ls memory. To change it, work in a clone of the repository (kortix workspaces clone, then cd into it; /workspace has none at boot) and use the file tools on its memory/ folder. Edits land on main through the normal change-request flow (below).

  1. Read memory/MEMORY.md (and list memory/) to see what's there.
  2. Identify the right file. Most additions fit overview.md, connections.md, conventions.md, or decisions.md. write a new file only when a topic deserves its own page.
  3. Change an existing file with edit. Keep entries short, factual, and consistent with the surrounding prose.
  4. If you added, renamed, or deleted a file, update MEMORY.md so the index matches the folder. The index is the table of contents every agent reads first — keep it accurate.
  5. If something turned out to be wrong, delete it (rm). Don't leave stale facts to confuse future agents.

Landing memory on main

Session branches die when sessions end. Memory edits reach main only via a Kortix change request — same path as any code change:

git add -A -- memory
git commit -m "memory: <one-line summary of what changed>"
git push origin HEAD
kortix cr open \
  --title "memory: <one-line summary>" \
  --description "What changed and why."

The user reviews and merges. Don't merge your own CR.

</writing> <curator>

A new workspace has no scheduled memory curator. To add one, add an agent (for example agents/memory-curator.md) and a cron trigger in kortix.yaml that runs it. The kortix-harness-refinement skill describes the full reflection protocol; memory curation is one of its passes. On each run the curator:

  1. Loads this skill.
  2. Surveys recent workspace activity (git log since last run, recent merged CRs, session digests via kortix sessions digest).
  3. Decides what's worth keeping per the rubric above.
  4. CRUDs memory/ accordingly.
  5. Opens one memory: … CR with the edits. It does not merge it.
  6. Leaves memory untouched when nothing is worth changing.

Kortix manages this skill: an edit to it is replaced on the next update. To change what gets remembered, write the workspace's own rules into the curator's prompt. A merged CR takes effect on the next run.

</curator> <gotchas>
  • The index is read first; sub-files are on demand. Don't dump every fact into MEMORY.md — keep it a clean table of contents and push depth into sub-files the agent reads only when relevant.
  • Read your memory before you start. Nothing is auto-injected; if you skip memory/MEMORY.md, you work blind to what the workspace already knows. The agent rules say the same thing — this is the memory protocol.
  • Memory files are markdown, not databases. Avoid heavy formatting, tables of 50 rows, or auto-generated content. If you catch yourself writing a script to generate a memory file, that content probably belongs in code, not memory.
  • Memory edits must go through CR. Direct pushes to main bypass the user-review contract — the same rule as code. Every memory edit ends with kortix cr open.
  • Don't put secrets in memory. Memory is read into context and committed to the repo. Secrets, tokens, API keys, and PII belong in the Kortix Secrets Manager, surfaced as env vars at runtime — not in memory/.
</gotchas> </skill>