Skip to content

feat: add shared project memory API for chats in a project - #29301

Merged
f0ssel merged 73 commits into
mainfrom
f0ssel/chat-project-memories
Oct 5, 2026
Merged

f0ssel merged 73 commits into
mainfrom
f0ssel/chat-project-memories

Conversation

@f0ssel

@f0ssel f0ssel commented Sep 14, 2026 •

Copy link
Copy Markdown
Member
  • Experiment, stacked on feat: add chat projects API #29242. UI is in feat: add chat project folders to the sidebar #29583.
  • Adds project memory: chat_project_memories rows with a name (lowercase slug, unique per project), a one-line description (150 characters) and a body (8KB). Up to 200 per project, shared by every root chat in the project. Chats outside a project and subagents have no memory.
  • Memories are immutable: they are created and deleted, never edited. Agent tools are read_memory, save_memory, delete_memory and consolidate_memory. Saving an existing name fails and points the agent at consolidate_memory to replace it.
  • Consolidation is agent-driven, in the turn, modeled on how Claude Code compacts its memory index when warned it is near its limit. From 160 memories (80%), save results ask the agent to get under 140 (70%) with consolidate_memory, choosing what to merge and drop. That tool deletes and saves memories in one transaction under the per-project advisory lock, and rolls back entirely if a delete is missing, a name is taken, or the result exceeds 200. There is no background extraction or consolidation.
  • The memory index reaches the model as model-only conversation messages, not in a tool description or the system prompt. At turn start the chat gets a full <project-memory-index> snapshot when its prompt has none (first turn, or after compaction), otherwise a <project-memory-index-update> listing only what changed. Tool definitions and the system prompt carry no memory state, so memory writes never invalidate the provider's cached prompt prefix. Writes by other chats, or by this chat mid-turn, reach the model at its next turn.
  • REST API (create, list, get, delete) under /api/experimental/organizations/{organization}/chats/projects/{project}/memories. Memory permissions follow projects onto the agents-access role.
  • Every memory change is audited as ChatProjectMemory create or delete. REST changes are attributed to the caller. Tool changes (save_memory, delete_memory, consolidate_memory) are attributed to the chat owner, carry the chat_id, and record one entry per memory after the change commits, so a rolled-back consolidation records nothing.

Examples

What the model sees. The system prompt gets a fixed guidance block with no memory state:

<memory>
Memory is durable context shared by every chat in the project "platform".
Save facts that will matter in future chats: … The memory index is in the conversation: a <project-memory-index> message lists every saved memory, and <project-memory-index-update> messages at the start of later turns list what changed. Changes made during a turn, including your own, appear in the next turn's update. … Memories cannot be edited: replace one that no longer holds with consolidate_memory, or delete it.
</memory>

On the first turn, after the user's message, the chat gets a model-only row with the full index (hidden in the UI):

<project-memory-index>
- deploy-day: Deploys happen on Tuesdays
- release-owner: Alice owns releases; ping her before tagging
</project-memory-index>

On a later turn where memories changed, it gets only the difference:

<project-memory-index-update>
Added or changed:
- deploy-day: Deploys happen on Wednesdays (changed 2026-09-30)
- staging-url: Staging lives at staging.example.com
Removed:
- old-ci-notes
</project-memory-index-update>

Resulting request layout, with the provider's cached prefix unchanged by memory writes:

[tools: fixed]  [system: fixed <memory> guidance]  [turn 1 user] [index snapshot] [assistant/tools …]  [turn 2 user] [index update] [assistant …]

Tool calls and results (produced by the tools in this PR):

save_memory {"name":"staging-url","description":"Staging lives at staging.example.com","body":"Staging is https://staging.example.com; deploys from main."}
→ {"count":3,"saved":"staging-url"}

save_memory {"name":"deploy-day", …}   // name already exists
→ error: a memory named "deploy-day" already exists; read it, then replace it with consolidate_memory by deleting "deploy-day" and saving the new version in one call

consolidate_memory {"delete":["deploy-day"],"save":[{"name":"deploy-day","description":"Deploys happen on Wednesdays (changed 2026-09-30)","body":"The team deploys every Wednesday since 2026-09-30."}]}
→ {"count":3,"deleted":["deploy-day"],"saved":["deploy-day"]}

read_memory {"name":"deploy-day"}
→ {"name":"deploy-day","description":"…","body":"…","created_at":"2026-09-30T15:04:05Z","created_by":"alice"}

Near and at the cap:

save_memory … → {"count":160,"saved":"one-more","warning":"memory is 160/200, approaching the limit. Consolidate it to under 140 memories now with consolidate_memory: merge overlapping memories into one, and drop stale, wrong, or superseded ones."}

save_memory … → error: memory is full (200/200); use consolidate_memory to merge overlapping memories and drop stale ones, and include this memory in its save list

REST memory object (GET .../chats/projects/{project}/memories):

{
  "id": "59500000-0000-4000-8000-000000000001",
  "project_id": "7c0e4a3e-5b1f-4f7d-9a51-2f3c8f6d2b10",
  "organization_id": "bb640d07-ca8a-4869-b6bc-ae61ebb2fda1",
  "name": "deploy-day",
  "description": "Deploys happen on Wednesdays (changed 2026-09-30)",
  "body": "The team deploys every Wednesday since 2026-09-30.",
  "created_by": "0ed9befc-4911-4ccf-a8e2-559bf72daa94",
  "created_by_username": "alice",
  "created_at": "2026-09-30T15:04:05Z"
}

Create takes {"name", "description", "body"} and answers 409 on a duplicate name or at the cap.

Screenshots (predate the immutable-memory rework; tool output shape has since changed)

save_memory
read_memory
Agent reads every memory


Generated with Coder Agents on behalf of @f0ssel.

@github-actions

github-actions Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@f0ssel f0ssel added the experimental Changes that might not necessarily be merged, until its approved to proceed with. label Sep 14, 2026
@f0ssel
f0ssel force-pushed the f0ssel/chat-project-memories branch from a350928 to feef295 Compare September 14, 2026 19:22
@f0ssel

f0ssel commented Sep 14, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 14, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-22T00:16:57.752932Z 265fd6a Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: feef2952ae

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread coderd/x/chatd/projectmemory_extract.go Resolved
Comment thread coderd/x/chatd/projectmemory_extract.go Resolved
Comment thread coderd/x/chatd/projectmemory_extract.go Resolved
Comment thread coderd/chat_project_memories.go Resolved
Comment thread coderd/chat_project_memories.go Resolved
@f0ssel
f0ssel force-pushed the f0ssel/chat-project-memories branch from feef295 to 55ca548 Compare September 15, 2026 15:32
@f0ssel
f0ssel force-pushed the f0ssel/chat-project-memories branch 2 times, most recently from cc67953 to 99d30ca Compare September 15, 2026 22:52
@f0ssel
f0ssel force-pushed the f0ssel/chat-project-memories branch from 99d30ca to ba13328 Compare September 16, 2026 14:51
…cts experiment

Adds a lightweight chat_projects table and a nullable chats.project_id
binding so agent chats can be grouped inside an organization-scoped
project. Chats stay independent by default; deleting a project detaches
its chats instead of deleting them.

Backend: chat_project RBAC resource (org members read/create, creators
and org admins update/delete), audited CRUD under
/api/experimental/chats/projects, project_id on chat create/update and
list filter, codersdk client methods.

Frontend: experiment-gated Projects sidebar section with create/edit/
delete dialogs, /agents/projects/:projectId page, new-chat-in-project via
?project=, and a Move to project action in the chat menus.
Single-project responses previously scanned the organization's project
list to recover chat_count. A dedicated count query shares the list
predicate, and the converter now requires the count so no response can
silently report zero.
@f0ssel
f0ssel force-pushed the f0ssel/chat-project-memories branch from da3869f to 69c4eeb Compare September 17, 2026 16:43
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

All contributors have signed the CLA ✍️ ✅
Posted by the CLA Assistant Lite bot.

@f0ssel

f0ssel commented Sep 17, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 69c4eebd80

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread coderd/x/chatd/projectmemory_extract.go Resolved
Comment thread coderd/x/chatd/projectmemory_extract.go Resolved
Comment thread coderd/chat_project_memories.go Resolved
Silently dropping project_id returned every chat as if it were the
project's contents. The list now fails the same way create and update do.
Gives every chat in a project a durable, shared memory store modeled on
Claude Code's auto memory. Root chats in a project get a <project-memory>
index in the system prompt (guidance plus one line per memory, capped at
200 lines / 25 KiB with an explicit truncation notice) and read/save/delete
tools that upsert by name. Memories carry a name, one-line description,
and markdown body and are sanitized before storage.

After each completed root turn a detached, cursor-fenced extraction call
reviews new user messages and records facts the agent did not save itself.
It is create-only and skips turns where the agent used the memory tools,
so it cannot overwrite or delete existing memories.

Adds the chat_project_memory RBAC resource (org members may read and
write), audited CRUD under /chats/projects/{project}/memories, and a
Memory section on the project page listing collapsed memories that expand
to show the body with edit and delete.
…escription

The system prompt block now carries only the guidance, so the prompt
prefix is identical across turns and stays cacheable. The live index is
rebuilt each turn in the read_project_memory tool description.
…in a transaction

Extraction now claims the chat in the cursor row before running, drains
turns that complete while it works, and releases the claim afterward, so
overlapping turns never run two extractors over the same window. Tool-use
suppression applies per turn instead of to the whole lagging window.

Memory creation from the tool, the API, and the extractor runs the cap
count and insert in one transaction behind a per-project advisory lock.
f0ssel and others added 7 commits September 29, 2026 18:34
…memory failures

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Renumber the chat projects migration to 000606 after main added 000605.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…l/chat-project-memories

Renumber the chat project memories migration to 000607 after the projects
migration moved to 000606.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Count a user's projects across organizations under a per-owner advisory
lock so concurrent creates cannot overshoot, and answer 409 at the cap.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…l/chat-project-memories

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Comment thread coderd/x/chatd/chattool/memory.go Resolved
Comment thread coderd/x/chatd/chattool/memory.go Resolved
…refix

The memory index lived in the read_memory tool description and was rebuilt
before every model call, so any memory write changed the tools block and
invalidated the provider's cached prefix (tools, system prompt, history) for
every active chat in the project, mid-turn included.

Deliver the index as model-only conversation rows instead, the way Claude
Code loads MEMORY.md into conversation context rather than a tool or system
prompt. At turn start the generation loop commits a full snapshot when the
prompt has none (first turn, or after compaction) and otherwise only the
changes since the model last saw it. read_memory's description is now fixed.
Mid-turn, only a snapshot dropped by compaction is restored, and never
between an assistant step and its tool results.

Drop the index truncation branch, which could not trigger at the cap.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@linear-code

linear-code Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

CODAGT-1041

CODAGT-1045

f0ssel and others added 2 commits September 30, 2026 17:23
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…l/chat-project-memories

Move the memory index sync into runGenerationStep, which main split out of
the generation loop.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
f0ssel pushed a commit that referenced this pull request Oct 1, 2026
- Experiment, behind `chat-projects` (off by default). First of three
stacked PRs: #29301 (memory), #29583 (UI). This PR is API only; the
screenshots below are from the UI in #29583.
- CRUD under
`/api/experimental/organizations/{organization}/chats/projects/{project}`.
`GET /api/experimental/chats/projects` lists the caller's projects
across all organizations.
- `project_id` on chat create and as a chat list filter. A chat joins a
project only at creation; there is no move.
- Projects are identified by ID. Names are display labels (64
characters, description 1024) with no uniqueness constraint. An optional
`icon` URL (usually an emoji image under `/emojis`) is capped at 256
characters and audited.
- A user can own at most 100 projects across all organizations; creating
another answers 409. Creates count and insert under a per-owner advisory
lock so concurrent requests cannot overshoot.
- Projects are private to their `owner_id`. Members may only create
their own, and a chat can only be bound to a project its owner owns. An
unreadable or foreign project on chat create answers 404 so IDs cannot
be probed; a project from another organization answers 400.
- Permissions ride on the `agents-access` role next to chats (after
#30004), so whoever can use Coder Agents can use projects. Owners and
org admins reach every project.

### Examples

Create a project in an organization:

```http
POST /api/experimental/organizations/{organization}/chats/projects
{"name": "Platform", "description": "Infra and deploy work", "icon": "/emojis/1f680.png"}
```

```json
{
  "id": "7c0e4a3e-5b1f-4f7d-9a51-2f3c8f6d2b10",
  "organization_id": "bb640d07-ca8a-4869-b6bc-ae61ebb2fda1",
  "owner_id": "0ed9befc-4911-4ccf-a8e2-559bf72daa94",
  "name": "Platform",
  "description": "Infra and deploy work",
  "icon": "/emojis/1f680.png",
  "created_at": "2026-09-30T15:04:05Z",
  "updated_at": "2026-09-30T15:04:05Z"
}
```

List the caller's projects across organizations with `GET
/api/experimental/chats/projects` (an array of the object above). Update
with `PATCH .../chats/projects/{project}` and any of `name`,
`description`, `icon`; delete with `DELETE`, which detaches its chats.

Create a chat in the project, and list only its chats:

```http
POST /api/v2/chats
{"organization_id": "bb640d07-…", "project_id": "7c0e4a3e-…", "content": [{"type": "text", "text": "Plan the deploy"}]}

GET /api/v2/chats?project_id=7c0e4a3e-…
```

At the limit:

```json
409 {"message": "You can have at most 100 chat projects. Delete a project to create another."}
```

<details>
<summary>Screenshots (UI from #29583)</summary>

![Create
project](https://raw.githubusercontent.com/coder/coder/f0ssel/chat-projects-assets/v3/pr1-01-create-project-dialog.png)
![Sidebar
folders](https://raw.githubusercontent.com/coder/coder/f0ssel/chat-projects-assets/v3/pr1-02-sidebar-folders.png)
![Project
page](https://raw.githubusercontent.com/coder/coder/f0ssel/chat-projects-assets/v3/pr1-03-project-page.png)
![Folder
menu](https://raw.githubusercontent.com/coder/coder/f0ssel/chat-projects-assets/v3/pr1-05-folder-menu.png)
![Another member sees no
projects](https://raw.githubusercontent.com/coder/coder/f0ssel/chat-projects-assets/v3/pr5-member-sees-no-projects.png)

</details>

---
Generated with Coder Agents on behalf of @f0ssel.

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Base automatically changed from f0ssel/chat-projects to main October 1, 2026 15:49
…emories

Renumber the chat project memories migration to 000608 after the chat
projects migration moved to 000607.
Comment thread coderd/x/chatd/chattool/memory.go Outdated
return fantasy.NewTextErrorResponse(err.Error()), nil
}
memory, err := store.Get(ctx, name)
if err != nil {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should check for the not found error specifically and only then return "memory was not found", otherwise return a generic error message so we don't gaslight the model.

_, _ = b.WriteString("No memories saved yet.\n")
}
for _, entry := range entries {
_, _ = fmt.Fprintf(&b, "- %s: %s\n", entry.Name, entry.Description)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is less of a concern until we add project sharing, but we should eventually add escaping to the descriptions before adding them to the context. It isn't merged yet, but I have a helper for doing so in the agent plugins work: https://github.com/coder/coder/pull/29323/changes#diff-37e468454bbdcfdc10afd485d397409fe21701ec3dd81f1771a2fb4b67cd0ec6R124

I'm OK punting on this for now since this isn't the only place where we add arbitrary values into our XML-ish sections. Separately, I'm going to create a linear issue to clean up the other cases and flag this as a potential spot to investigate.

@jscottmiller jscottmiller left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall lgtm. Two things we may want to follow-up on as this work progresses: 1) I'm not sure what our criteria is for adding activity to the audit log, but memory activities (especially if shared) and 2) memories can be added and removed from plan mode - adding is fine but removing/consolidating might be surprising in plan mode.

@jaaydenh
jaaydenh added this pull request to stack #30295 October 2, 2026 16:42
f0ssel added 5 commits October 2, 2026 18:18
…emories

Renumber the chat project memories migration to 000612 after main took
000608 through 000611.
save_memory, delete_memory, and consolidate_memory now record a
ChatProjectMemory audit entry for every memory they create or delete,
attributed to the chat owner and naming the chat. Entries are written
after the change commits, so rolled-back consolidations record nothing.
DeleteChatProjectMemoryByName returns the deleted row for the entry.

read_memory now reports "not found" only when the memory is missing,
not on other read failures.
A step can commit some tool results while others, such as client
dynamic tools, are still pending. The index snapshot could then land
between the assistant's tool calls and their results, which providers
reject. Skip it mid-turn until every call in the latest assistant step
has a result.
@f0ssel
f0ssel merged commit a08ba6a into main Oct 5, 2026
52 of 54 checks passed
@f0ssel
f0ssel deleted the f0ssel/chat-project-memories branch October 5, 2026 16:52
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

experimental Changes that might not necessarily be merged, until its approved to proceed with.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants