Memory

Agents forget everything when a session ends. ORG-2 keeps two persistent stores that survive it: workspace memory, a directory of markdown files describing this workspace and the people working in it, and learnings, a database of behavioural insights an agent drew from its own past sessions. Both are written on your machine, both are readable and editable by you, and both are pulled back into a prompt only when something looks relevant.

The two layers

A running summary of the current conversation also exists, but that is part of the context-window pipeline for one session, not long-term memory.

What gets remembered

Workspace memory files carry a type in their frontmatter, and each type has a different job:

• user — role, goals, responsibilities, domain knowledge, so the agent can pitch its work at the right level.
• feedback — guidance you have given about how to approach work. Both corrections and confirmations: saving only corrections would avoid past mistakes but drift away from approaches you already validated.
• workspace — ongoing work, goals, incidents and decisions not derivable from code or git history. These decay fastest, so relative dates are converted to absolute dates when saved.
• reference — where information lives in external systems, e.g. which Linear initiative tracks bugs.

What does not get remembered

The extractor is told not to save anything that can be re-derived. It skips code patterns, conventions, architecture, file paths and workspace structure (read the workspace instead); git history and who-changed-what (git log and git blame are authoritative); debugging solutions and fix recipes (the fix is in the code); anything already covered by a rule or config file; and ephemeral task state.

These exclusions hold even when you ask for a save. Ask an agent to remember a PR list or an activity summary and it is instructed to ask what was surprising about it instead — that is the part worth keeping.

How memory is written

Three write paths, none of which requires you to do anything:

1. Per-turn extraction. After a turn, the built-in Memory Extractor reads the last few messages and decides whether anything durable happened. It can only use read tools plus edit_file restricted to the memory directory, and is told not to research or verify — only to record what the transcript already showed. It skips entirely when the main agent wrote to memory itself that turn.
2. Saving is two steps: write the content to its own file (user_role.md, feedback_testing.md), then add a one-line pointer to MEMORY.md, the index. Content never goes directly into the index. Ask an agent to remember something and it saves immediately; ask it to forget and it removes the entry.
3. Auto-dream consolidation. The built-in Memory Consolidator merges redundant or stale files in the background, only after at least 24 hours and 5 sessions since the last run, holding a lock so two processes never consolidate at once.

Separately, when a session ends a reflection pass can extract behavioural insights into the learnings table as pending, and a pattern-miner files repeated tool-error-then-user-correction sequences as observations. Consolidation later decides whether each pending row is added, merged, or dropped.

Note: These subagents run in the background and discard their events, so memory writes do not appear as steps in your session trajectory. You see the result in the memory browser, not in the transcript.

How memory is retrieved into context

At the start of a turn, ORG-2 runs a side-query in parallel with the main loop. It shows a selector model your message plus a manifest of every memory file — type tag, filename, timestamp, description — and asks which are clearly useful. It is told to be selective and return an empty list rather than guess, and to skip API-reference memories for tools already in use while keeping memories that record gotchas about those tools.

Up to 5 memories are selected, capped at 50,000 bytes. They arrive as a system section headed # Workspace Memory containing:

• the MEMORY.md index, truncated past 200 lines or 25,000 bytes with a visible notice,
• the full text of each selected memory, labelled with its path,
• a freshness caveat on anything over a day old, stating its age and warning that file:line citations may be outdated,
• guidance on when to access memory and on verifying claims before acting.

That guidance matters: a memory naming a function or file is a claim about when it was written. The agent is told to check the file exists or grep for the symbol before recommending it, and to trust what it observes now over what it recalls. Tell an agent to ignore memory and it is told to proceed as if MEMORY.md were empty, not to acknowledge and then quietly apply it anyway.

If the side-query fails, the session falls back to the newest memories rather than losing memory entirely, and memories already surfaced earlier in the session are not re-injected.

Learnings follow a different path: active learnings are ranked by salience and rendered into a ## Learned Insights section on every turn, bucketed by age, capped at 120 lines. The learnings read path is deliberately not gated by the per-agent write toggle — turning off capture still lets you benefit from what was already recorded.

Cross-session, cross-agent, and workspace scope

Workspace memory is scoped to a workspace, not to a session or an agent. Every agent working in that repo reads and writes the same .orgii/workspace-memory/ directory, so a fact one agent learns is available to the next agent and the next session. There is no separate shared scratchpad — this directory is the shared knowledge base; direct agent-to-agent coordination goes through messages and tasks instead.

A second, personal scope exists: the OS Agent works out of a personal workspace, and its memory sits flat at ~/.orgii/personal/workspace-memory/. The browser exposes both as Personal and Workspace.

Learnings are scoped globally or per agent (agent:<agent-id>), so one agent's behavioural corrections do not silently rewrite another's, and they live in the shared database rather than any one repo.

Project knowledge the agents read

Memory is for what agents discover. For conventions you want to state up front, ORG-2 reads two things from your project.

<project>/.orgii/agent-rules.md is the project conventions file. If it exists, its contents go into the system prompt under a ## Project Conventions heading for every workspace session, capped at 20,000 bytes. Put your build commands, house style, and "never do X in this repo" notes here.

Rules are individual markdown files injected on every turn:

A rule's frontmatter carries description, an optional globs file pattern, and alwaysApply. Keep rules under about 100 lines — they are read on every turn. ORG-2 can also detect and import rule-shaped files you already keep for other tools, including Cursor .mdc rules, CLAUDE.md, and AGENTS.md, into .orgii/rules/.

Reviewing, editing, and pruning

Go to Integrations → Rules, Memory & Evolution → Memory. Switch between Personal and Workspace scope, then search, sort by name, age or type, and filter by type. You can open a file to read or edit it in place, open View MEMORY.md to inspect the index, delete a single file, or use Clear all memory files to wipe the workspace's memory — both deletions are confirmed and irreversible. You can also just open the directory and edit the markdown in any editor; the files are the source of truth.

Learnings have their own Learnings Browser, with tabs for Pending, Active, Merged, Deprecated and Abandoned, and per-row Promote, Deprecate, Reactivate and Delete. Only active learnings reach the prompt, so promoting is an explicit decision.

Each agent has a Memory & Evolution tab with three switches: Long-term memory, Extract memories from sessions, and Auto-dream consolidation. The two extraction switches default off on a new agent definition; the built-in agents enable them.

Privacy

Memory is local. Workspace memory is plain markdown on your disk, learnings are rows in a local SQLite database, and both are written by processes on your machine. Nothing in the memory subsystem is uploaded as a side effect of using ORG-2 — the same local-first posture as the rest of the runtime. Two caveats:

• Project-scoped memory lives in your repo. Whether .orgii/workspace-memory/ is shared depends entirely on your .gitignore — ORG-2 does not add an entry for you. Sharing it is often what you want; if it is not, ignore .orgii/. Either way, review the files before committing, because a user or feedback memory can record things about you or your colleagues.
• Selection uses your model provider. The relevance side-query sends your message and the memory manifest to whichever model provider you configured, and the selected memory bodies go into that session's prompt. Memory sits behind the same provider trust boundary as everything else you send. See Security for key storage and provider traffic, and Cloud for what the managed backend holds.

For an agent that keeps nothing, turn off Long-term memory and both extraction switches for that agent, then clear the workspace's memory files.

Next steps

• Security — the trust boundary, key storage, and what leaves your machine
• Cloud — ORG-2 Cloud versus self-hosted Supabase
• Skills — the sibling system for procedures you write yourself
• Sessions — what a session records and how the transcript is stored