Type to search the docs and updates.

Browse documentation

Shared memory

Save a project fact once and every coding tool reads it next session. Facts are Markdown files, so your team reviews them in Git.

Turn it on

Add memory to agnostic-ai.yaml, then sync once:

requires: ">=0.92.0"
builtins: [memory]
agnostic-ai sync

Saving a fact needs no further sync.

  • To enable it for all projects, use global configuration instead. Pick one, or facts can load twice.
  • Claude Code needs a project sync either way.

Two memories

Project memoryPersonal memory
Folder.agnostic-ai/memory/.agnostic-ai/local/memory/
In GitYes, shared with the teamNo, stays on your machine
HoldsTeam facts: conventions, decisions, known problemsYour preferences and corrections
Tools saveAfter you confirmWithout asking

Each folder holds one file per fact and a MEMORY.md list. Tools read the list at session start and open a fact when needed.

.agnostic-ai/memory/
  MEMORY.md        # - [CI runs on Ubuntu](ci-ubuntu.md): PR CI skips macOS and Windows
  ci-ubuntu.md

Save and recall a fact

  1. Tell your tool: “Remember that this project's integration tests need the local database running.”
  2. It proposes the team fact. You approve it. (A personal preference, such as shorter answers, saves without asking.)
  3. Start another tool and ask what it knows about integration tests.
  • Keep your tool's own memory on. Shared memory adds to it (Gemini CLI keeps both).
  • Your request wins over saved facts.
  • Ask for the shared-memory skill to recall a topic or clean up stale facts. Cleanup needs your confirmation.

Check and repair

agnostic-ai lint and doctor flag:

  • lists over 100 lines each or 6,000 bytes combined
  • broken links and unlisted facts
  • possible secrets and hidden characters

They skip personal memory when its folder is missing, as in CI. agnostic-ai memory lint runs only these checks. agnostic-ai memory index rebuilds each MEMORY.md after a merge conflict (memory commands).

Write or review a memory fact by hand

A fact file:

---
name: ci-ubuntu
description: PR CI runs on Ubuntu alone
metadata:
  type: project
---

PR CI runs on Ubuntu alone.

**Why:** the full OS matrix costs too much to run on every push.

**How to apply:** run the full matrix before merging a change to file paths.

type is user, feedback, project, or reference. The sources: setting does not move these folders.

The shared-memory-policy rule asks tools to save only facts the code, history, and rules lack; to update a fact rather than add a duplicate; to check that named files and commands still exist; and to never save secrets. Review shared memory changes like code, because every tool reads them.

How each tool loads memory and keeps its own notes

How each tool loads it

ToolHow
Claude CodeCLAUDE.md imports the project list, and Claude Code's own memory loads the personal list
Codex, Copilot, Gemini CLI, Qoder, FactoryA command runs when a session starts and adds both lists
Devin CLI (windsurf)A SessionStart command adds both lists through tagged context; the rule remains a fallback
Cursor local sessions and self-hosted workersA command runs when a session starts and adds both lists
Trae with project hooks enabledA command runs when a session starts and adds both lists
Cline VS CodeA project TaskStart hook returns both lists through contextModification; the shared rule remains the fallback
Auggie CLI (macOS, Linux, Windows WSL)Documented 0.x behavior: a SessionStart script adds both lists. In 1.x, use the memory rule fallback (details)
OpenCode, Kilo CodeThe config lists both files
KiroA steering file includes project memory and, in checkout mode, personal memory
AntigravityAn always-on rule includes project memory and, in checkout mode, personal memory
Every other toolA rule tells the tool to read both lists before a task
  • Kiro shows a marker for an included list that has no file yet. The marker goes away once a tool saves a fact there.
  • If you added the include to a steering file by hand, remove it.
  • With memory.personal: repo, Kiro and Antigravity include only the project list. They find personal memory with agnostic-ai memory path.
  • With sync --global, both get only the rule, because a home file cannot name a project's lists.
  • See Kiro and Antigravity shared memory (rule size limits).

Aider gets only the rule, because a missing file shows an error. Once both MEMORY.md files exist, add them yourself in .aider.conf.yml: read: [.agnostic-ai/local/memory/MEMORY.md, .agnostic-ai/memory/MEMORY.md]

When a session starts

On Codex, Copilot, Cursor, Gemini CLI, Qoder, Factory, Trae, and Devin CLI, sync adds a hook that runs agnostic-ai hook memory when a session starts. In Trae, enable project hooks in Settings > Hooks first.

Auggie documents startup context injection in 0.x. Its 1.x docs say SessionStart runs in the background without adding output to context, so use the memory rule that tells the agent to read both lists. Sync still emits the hook; see Augment shared memory.

  • Looking upward from the folder the tool starts in, the hook runs the first node_modules/.bin/agnostic-ai it finds up to the project's config. Otherwise it runs the agnostic-ai on your PATH. Trae runs the PATH one only.
  • agnostic-ai project then finds the project and runs its pinned version.
  • Keep the one it picks up to date with agnostic-ai upgrade. An older one prints an upgrade message. With none found, nothing loads.
  • Codex, Cursor, Gemini CLI, and Qoder run it only in a folder you trust.
  • On Windows, Cursor and Gemini CLI need sh on PATH, for example from Git Bash. The Claude Code subagent hook needs it too.
  • Hooks you wrote yourself stay.
  • It keeps the first 6,000 bytes, after dropping hidden characters. Facts past the cut never load on these tools, and memory lint names them (the first 10). Every other tool loads both lists whole, hidden characters included, so memory lint also warns there once they pass 6,000 bytes. Remove the hidden characters it reports.

Cline VS Code gets a project-only memory-cline-task-start hook, which needs Cline for VS Code 4.1.20 or later with hooks enabled. Global sync leaves it out, because the Cline SDK and CLI ignore TaskStart hook replies. See Cline VS Code memory startup.

Devin CLI uses the memory-windsurf-session-start hook with an explicit POSIX sh launcher and a 10-second timeout. It starts from DEVIN_PROJECT_DIR even when its process runs elsewhere. Native Windows hook execution is undocumented.

Cursor's hosted cloud agents do not run sessionStart hooks or user-level hooks. They read the project index through the shared memory policy and skill. Local sessions and self-hosted workers run the hook. See Cursor's cloud hook support.

Claude Code's own memory

Claude Code also saves facts by itself. Sync points that memory at your personal memory folder (autoMemoryDirectory in .claude/settings.local.json), so its saves land where every other tool reads them. Sync keeps a value you set yourself, and Git never commits the file. Claude Code uses the setting once you trust the folder.

Claude Code then loads your personal list as its own memory: the first 200 lines or 25KB, with hidden characters cleaned out.

  • CLAUDE.md imports only the project list.
  • Claude Code's own memory never reaches a subagent. So a SubagentStart hook runs agnostic-ai hook memory to add the personal list.
  • In a linked worktree that uses the main checkout's personal folder, the hook reads that same folder.

CLAUDE.md imports both lists, and the hook adds nothing, in these cases:

  • Auto memory is off (autoMemoryEnabled: false in a settings file, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in your shell or a settings env block).
  • Your own autoMemoryDirectory points to another folder.
  • A settings file sets permissions.blockReadsOutsideWorkingDirectories: true and the folder comes from repository-supplied settings (for example, a tracked local file or a local file outside Git).
  • sync.unmanaged prevents sync from setting the folder.

Run agnostic-ai sync after you change these settings.

Facts Claude Code saved before come along. When personal memory is still empty, the first sync that points Claude at it copies them from Claude's own folder (~/.claude/projects/<project>/memory/) and leaves that folder as it is. Otherwise agnostic-ai lint names the folder and how many of its facts no longer load (LINT043), and this copies them over:

agnostic-ai memory import --from claude --dry-run
agnostic-ai memory import --from claude

Every tool reads personal memory, so the dry run lists each fact with its description first; --only <file> copies just the ones you pick. To clear LINT043 for the rest, decline them with --skip <file> or --skip-rest. --path copies from any folder with the same layout, such as Gemini CLI's ~/.gemini/tmp/<project>/memory/ or Qoder's ~/.qoder/projects/<project>/memory/. See memory import.

Each tool's own memory

To share something a tool learned, ask it to save the fact in shared memory. Claude Code's own saves land there already, unless you set autoMemoryDirectory yourself.

ToolIts own memoryDefault
Claude CodeAuto memory: notes for each repository, on your machineOn (autoMemoryEnabled); sync points it at your personal memory folder
CodexMemories: notes built from past sessions, one store for the machineOff (memories under [features])
Gemini CLIEdits its own Markdown memory files: GEMINI.md files and private notes for each project. Auto Memory proposes notes from past sessions. Sync generates the project's GEMINI.md, so the gemini-memory-tiers rule sends Gemini's team facts to shared memory instead, and has it copy private facts there tooEditing is always on, with no setting. Auto Memory is off (experimental.autoMemory)
CopilotCopilot Memory, hosted: repository facts and your preferences, dropped after 28 days unused. The VS Code memory tool: notes on your machineCopilot Memory is on for individual plans; organization admins enable it first. CLI: /memory on or /memory off. The VS Code tool is built in
QoderCLI Auto-Memory: notes the agent keeps on your machine. The IDE has a separate memoryCLI: off (autoMemoryEnabled). IDE: not documented
Kilo CodeKilo Memory: project notes outside the repository, no personal memoryOff (Settings > Context, or /memory on)
KiroMemory: learned notes stored per user account, shared by the IDE and CLIIDE 1.4.236+: open Memories and use the gear in the title bar. Earlier IDE versions use the Kiro Agent: Memory user setting. The default is Don't use, called Off before 1.4.215. In a local CLI V3 session, run /memories and choose config. Kiro memory settings
AugmentAgent Memories in the IDE, which you approve one by oneNot documented
TraeMemories, global and for each project, as local Markdown filesNot documented
GooseMemory extension: files in .goose/memory/ and ~/.config/goose/memory/Not documented (Extensions)
JulesMemory in the Jules cloud for each repositoryNot documented (repository settings)
Windsurf (Devin)Devin Local keeps none. Cloud Devin has its own MemoryCloud Devin Memory is on; whether it reaches Devin Desktop, Local, or the CLI is not documented
CursorNone documentedNot applicable
Share personal memory across linked worktrees

Share personal memory across worktrees

By default each checkout has its own personal memory, so deleting a worktree deletes what it learned. A worktree Claude Code creates starts with a copy when sync manages .worktreeinclude; any other starts empty. In a worktree, Claude Code reads the main checkout's .claude/settings.local.json, so its own memory uses the main checkout's personal memory once sync has run there.

To keep one personal memory for every worktree of a repository, add this to agnostic-ai.local.yaml and sync:

memory:
  personal: repo

For a new Git project, agnostic-ai init --memory enables shared memory and starts personal memory in this repo mode when managed ignores are on. It keeps an existing agnostic-ai.local.yaml. Without Git or with --gitignore=off, it enables memory in checkout mode. In checkout mode, sync names this option when linked worktrees exist.

A linked worktree without its own agnostic-ai.local.yaml follows the main checkout's memory.personal setting; its own local file takes precedence. Other settings stay local to each checkout, and each teammate chooses their own mode.

Personal memory then lives in ~/.agnostic-ai/local/memory/<repository name>-<hash>/ (under $AGNOSTIC_AI_HOME when set). Sync creates it, readable only by you, and it works when ~/.agnostic-ai is a link to another folder. Moving or recloning the repository starts a new folder. To see it:

$ agnostic-ai memory path
project   ~/code/app/.agnostic-ai/memory
personal  ~/.agnostic-ai/local/memory/app-fbcd84e8

When you change the mode:

  • The first sync copies facts into the new store if it holds no Markdown file, and prints the count. The old store stays unchanged.
  • If the new store already has facts, agnostic-ai lint names the ones left behind. agnostic-ai memory import --from checkout copies them over (--from repo when you switch back).
  • Dry runs, checks, and previews never copy facts.
  • Later syncs keep imported facts you deleted out of the store. An explicit memory import can bring them back.

Some tools need the store's full path in their config, because it is outside the project.

  • Sync writes the path only to files Git ignores. That needs the .gitignore block (gitignore.enabled: true, which agnostic-ai init sets).
  • The block lists those files, such as .codex/config.toml, whenever their tool and the memory built-in are on. So the committed .gitignore and .worktreeinclude stay the same for teammates without the setting, and a new Claude Code worktree copies them.
  • If one of those files is already in Git, run agnostic-ai sync --untrack.
  • To commit one instead, such as a hand-written .codex/config.toml, add its path to gitignore.allow.
  • A file kept in Git through gitignore.commit or gitignore.allow never gets the path, so that tool works as without the block. sync --gitignore off does the same for one run.

What each tool does with personal memory in this mode (project memory loads the same way in both columns):

ToolWithout the .gitignore blockWith it
Claude CodeLoads and savesSame
Copilot, FactoryLoadsLoads
Codex, Gemini CLI, QoderLoadsLoads and saves
CursorLoadsLoads; the CLI saves, the editor asks first
OpenCodeNothingLoads and saves
WindsurfFinds it with agnostic-ai memory pathSame; Devin CLI saves without asking
Kilo Code, Kiro, every other toolFinds it with agnostic-ai memory pathSame
  • Saving outside the project. Codex, Gemini CLI, Qoder, OpenCode, the Cursor CLI, and Devin CLI write only inside the project without asking. So sync gives them the folder:
    • Codex: writable_roots (read in workspace-write mode, in a trusted project).
    • Gemini CLI: context.includeDirectories.
    • Qoder: permissions.additionalDirectories.
    • OpenCode: permission.external_directory in opencode.json.
    • Cursor CLI and Devin CLI: a Write(<folder>/**) rule in .cursor/cli.json and in permissions.allow of .devin/config.json.
    • Every tool but Codex keeps your own entries. If your Codex overlay sets [sandbox_workspace_write], sync leaves it alone; add the folder there yourself.
  • Kilo Code ignores project config entries outside the project. To load personal memory every session, add its MEMORY.md to instructions in ~/.config/kilo/kilo.jsonc.
  • Tools with only the rule need agnostic-ai on PATH, and may ask before they read or write outside the project.
  • Cloud agents start from a fresh clone, so they never see personal memory.