---
title: "Shared memory for coding agents: notes anchored to code · Cork"
description: "Give AI coding agents shared memory: instruction files, path-scoped rules, auto memory, and notes anchored to functions so the right agent reads them."
canonical: "https://corkcli.com/blog/shared-memory-coding-agents-anchored-notes"
last_updated: "2026-11-14"
published: "2026-10-03"
author: "Kevin Vera"
---

# Shared memory for coding agents: notes anchored to code

Give AI coding agents shared memory: instruction files, path-scoped rules, auto memory, and notes anchored to functions so the right agent reads them.

By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 5 min read

Shared memory for coding agents means durable notes that every agent can read, so a decision one agent made ("this function keeps its signature because the webhooks call it") reaches the next agent that touches the same code. The most useful notes are anchored to code: attached to a directory, a file pattern, or better, a specific function, so they load only when an agent works there instead of crowding every session's context. You can build this today with nested instruction files and path-scoped rules; notes anchored to individual functions and shared across tools and machines need a shared store.

## What agents remember today, and what they do not

As of October 2026, the main coding agents have several kinds of memory, with different scopes.

| Mechanism | Who writes it | Scope | Shared with teammates? |
|---|---|---|---|
| `CLAUDE.md`, `AGENTS.md` (project root and nested) | You | Repo, directory | Yes, via git |
| Claude Code `.claude/rules/` with `paths` frontmatter | You | File patterns | Yes, via git |
| Cursor `.cursor/rules/*.mdc` with `globs` | You | File patterns | Yes, via git |
| Claude Code auto memory (`~/.claude/projects/<project>/memory/`) | Claude | One repo, one machine | No, machine-local |
| Conversation context | The session | One session | No |

Two gaps stand out. Instruction files are written by people and tend to hold rules, not the small decisions agents make during work. Auto memory captures those decisions, but Claude Code's docs say it is machine-local: files are not shared across machines or cloud environments, and only the first 200 lines or 25KB of the `MEMORY.md` index load at session start. Nothing on the list is shared across different agents on different machines at the level of a single function.

## Level 1: put notes next to the code they describe

The simplest anchor is location. Agents already load instruction files by directory:

- **Codex** concatenates `AGENTS.md` files from the project root down to the working directory (at most one per directory, 32 KiB total by default), with closer files taking precedence.
- **Claude Code** loads `CLAUDE.md` files above the launch directory at start, and loads subdirectory `CLAUDE.md` files on demand when Claude reads files there.
- **Cursor** supports nested `AGENTS.md` files in subdirectories.

So a note about the billing module belongs in `billing/AGENTS.md` (or `billing/CLAUDE.md`), not in the root file. Agents working elsewhere never pay for it.

## Level 2: anchor notes to file patterns

Path-scoped rules load only when an agent touches matching files. In Claude Code, a rule in `.claude/rules/` with `paths` frontmatter triggers when Claude reads, writes or edits a matching file:

```markdown
---
paths:
  - "src/billing/**/*.ts"
---

# Billing decisions
- sendInvoice() keeps its (invoice, opts) signature: webhooks/stripe.ts depends on it.
- Retries use exponential backoff from billing/retry.ts; do not add ad hoc loops.
```

Cursor does the same with `.mdc` files in `.cursor/rules` and the `globs` field. Keep both short; Claude Code's guidance is to target under 200 lines per `CLAUDE.md` file because longer files reduce adherence.

## Level 3: anchor notes to symbols

Files and globs are coarse. The decision above is about `sendInvoice`, not about every file in `src/billing`. Symbol-level anchoring means storing a note keyed to a function or type and surfacing it when an agent is about to read or change that symbol. A homegrown version:

1. Keep notes in a file keyed by symbol, for example `notes/symbols.json` with entries like `"billing/invoice.ts::sendInvoice": "Keep signature; webhooks depend on it."`
2. Add a pre-edit hook (Claude Code `PreToolUse`, Codex `PreToolUse`, Cursor `preToolUse`) that finds which symbols the edit touches and prints matching notes to the agent.
3. Add a session-start or prompt hook that prints notes for symbols the prompt mentions.

The hard parts: mapping an edit to symbols needs a parser per language, renames break string anchors, and a note file in git only updates when someone pulls.

## Keeping shared memory honest

Memory that is wrong is worse than none. Practices that help:

- **Write decisions with reasons.** "Keep the signature because X calls it" can be re-evaluated when X changes; "keep the signature" cannot.
- **Date or version notes**, and delete them when the code they describe is removed.
- **Prefer verifiable notes.** "Run `npm test -- billing` after changing retry logic" is checkable; vague advice is not.
- **Review memory like code.** Claude Code has a prompt audit (`/doctor prompt-audit`) that checks instruction files for outdated or conflicting guidance.
- **Treat notes as data, not orders.** A note from another agent should inform the reader, not override what the user asked for.

## How Cork helps

Cork provides the symbol-level layer as MCP tools: `remember` stores a durable note anchored to code, and `recall` reads notes back, so a decision about `sendInvoice` stays attached to `sendInvoice`. Cork's briefing does the surfacing: when an agent starts or gets a prompt, it is handed the exact signatures, callers and recent changes of the code it is about to touch. The same store serves Claude Code, Codex and Cursor through hooks with no extra model calls, plus the MCP server at https://mcp.corkcli.com. Cork Free keeps all data on your machine; the paid plan adds shared knowledge across teammates' machines.

Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned.

```bash
curl -fsSL https://corkcli.com/install.sh | sh
```

## Frequently asked questions

### Do Claude Code agents share memory?

Agents on the same machine and repo share Claude Code's auto memory directory, including across worktrees. It is machine-local and not shared across machines. `CLAUDE.md` and rules files are shared through git.

### Where should I store decisions for AI coding agents?

As close to the code as possible: a nested `AGENTS.md` or `CLAUDE.md` for a module, a path-scoped rule for a file pattern, or a symbol-anchored note for a single function.

### How do I stop agent memory from bloating context?

Scope notes so they load only when relevant (nested files, `paths` or `globs`), keep root files short, and delete stale notes.

## Sources

- <https://code.claude.com/docs/en/memory>
- <https://learn.chatgpt.com/docs/agent-configuration/agents-md>
- <https://cursor.com/docs/context/rules>
- <https://code.claude.com/docs/en/hooks>
- <https://learn.chatgpt.com/docs/hooks>
- <https://cursor.com/docs/agent/hooks>

## Related reading

- [How to coordinate AI coding agents across a team's machines](https://corkcli.com/blog/coordinate-ai-coding-agents-across-team): Coordinate AI coding agents across a team's machines: shared agent instructions, branch and PR rules, CI gates, live signals, and what built-in tools cover.
- [Multiplayer AI coding for remote teams](https://corkcli.com/blog/multiplayer-ai-coding-remote-teams): How remote teams run AI coding agents on one codebase: shared agent instructions, async handoffs, ownership, landing rules, and cross-machine awareness.
- [Running AI coding agents in a monorepo: what to watch for](https://corkcli.com/blog/ai-coding-agents-monorepo): What breaks when AI coding agents work in a monorepo: instruction files, context size, shared packages, affected tests and parallel agents, with fixes for each.
- [How to share context between Claude Code sessions](https://corkcli.com/blog/share-context-between-claude-code-sessions): Six ways to carry context between Claude Code sessions: CLAUDE.md, auto memory, handoff files, resume and fork, cross-session messaging, SessionStart hooks.

[All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt)

This page in HTML: https://corkcli.com/blog/shared-memory-coding-agents-anchored-notes