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
Файлы1
Открыть в GitHubSKILL.mdpackages/starter/templates/managed/skills/kortix-memory/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.
Landing memory on
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>
- 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>
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(thekortix-user-memoryskill). - 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-DDso readers can judge staleness. - Prefer editing existing entries over piling new ones on. A bloated file is worse than a tight one.
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).
- Read
memory/MEMORY.md(and listmemory/) to see what's there. - Identify the right file. Most additions fit
overview.md,connections.md,conventions.md, ordecisions.md.writea new file only when a topic deserves its own page. - Change an existing file with
edit. Keep entries short, factual, and consistent with the surrounding prose. - If you added, renamed, or deleted a file, update
MEMORY.mdso the index matches the folder. The index is the table of contents every agent reads first — keep it accurate. - 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:
- Loads this skill.
- Surveys recent workspace activity (git log since last run, recent
merged CRs, session digests via
kortix sessions digest). - Decides what's worth keeping per the rubric above.
- CRUDs
memory/accordingly. - Opens one
memory: …CR with the edits. It does not merge it. - 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
mainbypass the user-review contract — the same rule as code. Every memory edit ends withkortix 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/.