Agent notes

Claude Code, Codex, Kimi, Hermes and the rest each keep their own memory — on one machine, in one tool, never shared with the team. So the same agent makes the same mistake again next week, and a teammate's agent makes it too.

Agent notes are short lessons an agent saves for one repository while it works:

• a correction — a mistake it made and the right way ("Run API tests with npm test -w apps/api, not npx jest");
• a convention — a rule of the project that isn't written down;
• a gotcha — a trap in the code, tooling or environment;
• a decision — a choice made with you, and why.

At the start of every session codexguild_sync hands the agent the most useful notes for the repository it is in: pinned ones first, then the newest, about 1.5k tokens. The rest stay searchable with codexguild_notes.

How agents use them

The CodexGuild skill and the instruction block codexguild_advise proposes tell the agent to:

1. apply the notes it gets at session start;
2. save one short note (codexguild_note_save, ≤500 characters) when it corrects a mistake of its own, the user corrects it, or it learns an unwritten rule of the repository;
3. retire a note that proved wrong or outdated (codexguild_note_retire, with the reason).

Notes belong to the repository, identified by its git remote (github.com/owner/name), not to a folder on one machine: the same notes come back on your laptop and desktop, in Claude Code and in Codex. The local MCP server reads the remote for the agent and drops any credentials in the URL before anything is sent.

Learning from errors

With the CodexGuild hooks, the agent doesn't have to remember to take notes: every real error a command hits is remembered for the session, and at the end of a turn the agent is asked once whether what fixed it is worth a note for next time. It saves the note together with the original error — or simply finishes when there's nothing to keep.

Shared fixes (opt-in)

Turn on Share fixes in Dashboard → Notes and a note saved with the error it fixes also goes into a shared pool: the error's signature and the fix text, with secrets, e-mails and home paths removed — never the repository, the note or any code. Once two different accounts reported a fix for the same error, every agent that hits it gets the fix from codexguild_debug (and from the automatic failed-command lookup), marked as community-reported and unverified. Turning sharing off removes everything you shared.

Safety

Notes are replayed into every session, so they are guarded like code:

• Encrypted at rest. Each repository has its own AES-256 key, stored wrapped with a master key that only the CodexGuild server holds. A copy of the database alone reveals no note text.
• No credentials. A note that looks like it contains a key, token, password or connection string is refused.
• No injected instructions. Every note goes through the skill security scanner (prompt injection, pipe-to-shell, credential exfiltration, hidden Unicode…); anything it flags is refused.
• Teams approve. On a team repository, a note an agent saves waits until a person approves it in the dashboard; until then only the author's own agents use it.
• Never a permission. Notes steer how the agent works — they never replace your approval for installs, deletions or config changes.

Dashboard

Dashboard → Notes lists every repository with notes. Open one to read, edit, pin, retire, restore or delete notes, approve the team's pending ones, or forget the repository's notes entirely.

Limits per stage

Retired notes don't count. The live numbers are served at GET /v1/plans (features.notesPerProject).

REST

POST /agents/me/sync takes "repo" and returns notes with the result.