CodeAlmanac Saves What Agent Chats Forget

CodeAlmanac, Almanac’s open-source project by Divit from Almanac (YC S26), is a local codebase wiki for AI coding agents. It deals with the knowledge that Codex, OpenAI’s coding agent, and Claude Code, Anthropic’s coding agent, pick up in conversation and then forget when the chat ends. The takeaway is simple: try it when your repo has decisions, invariants, and cross-file workflows that agents keep rediscovering, but review its Markdown like code. The useful bridge for mcp training is that an mcp server can expose context safely, while CodeAlmanac shows why durable context is worth curating in the first place.

See what CodeAlmanac actually writes down

CodeAlmanac is a living Markdown wiki for a codebase, maintained from coding-agent conversations and stored inside the repo. A codebase wiki is the place where you write the things the code cannot say cleanly: why a queue is idempotent, which migration failed last time, why billing code avoids a tempting shortcut, or how a request crosses three services.

The repository says the project is mainly TypeScript, Apache-2.0 licensed, and, as of July 2026, has 559 GitHub stars. It supports macOS today with Codex or Claude Code, and requires Python 3.12+.

The interesting part is not that it writes docs. Lots of agents can summarize a chat into Markdown when asked. The interesting part is the background loop: CodeAlmanac installs local agent instructions and local macOS launchd jobs that scan recent Codex and Claude conversations, queue useful knowledge for the right wiki, garden stale or duplicated notes, and update the CLI when safe.

The trap is treating this like a transcript dump. A transcript is noisy. A useful wiki is selective. It should preserve decisions, invariants, flows, and gotchas, not every prompt that happened to produce a passing test.

We covered the first pass of this idea in CodeAlmanac Writes Wikis From Agent Chats, but the Hacker News reaction made the harder question clearer: can agents reliably decide what is worth remembering?

Why developers cared about the memory trick

The Hacker News interest was easy to understand. Coding agents are getting better at reading files, but they still lose the oral history that lives in review comments, Slack threads, previous failed attempts, and long debugging chats.

That missing context shows up as repeated work. An agent reopens an old design path. A human has to explain the same invariant again. A fix passes tests but violates a workflow nobody encoded in code.

CodeAlmanac’s bet is that those explanations already exist in agent conversations. If the tool can extract the reusable parts and keep them close to the repo, the next agent run starts with a better map.

The strongest objection is also fair: where is the evidence that this improves outputs or saves tokens? The public repo describes the workflow, not a benchmark. For now, the honest test is local and boring: pick a repo where agents repeat mistakes, install it on a small scope, and review whether the wiki prevents one real repeat.

Another objection was platform support. The README says CodeAlmanac supports macOS today, and its setup uses local launchd jobs. That sounds like a practical implementation choice, not proof that the idea is Apple-specific. Still, Linux and Windows shops should treat it as not ready for their default developer environment unless they are willing to adapt the scheduler pieces.

Try it where forgotten context hurts

CodeAlmanac makes most sense in a repo where the pain is not syntax. It is the repo where agents can edit code correctly but miss the reason the code is shaped that way.

A good starter target is a service with a few non-obvious invariants. For example, an orders service where refunds must be idempotent, webhook retries are expected, and a database column cannot be renamed until a partner export changes.

It is overkill for a tiny library with clear tests and little history. It is also risky if your team will never review generated docs. Stale memory is worse than no memory because it feels authoritative.

For Codex users, the clean mental model is close to the one used in the related training topic: durable repo instructions belong in files, task prompts belong in the current run, and external context needs boundaries.

Add one MCP boundary, not a context firehose

What is MCP in this story? Model Context Protocol (MCP) is a standard way for an AI client to connect to tools and data through servers, instead of pasting everything into the prompt.

CodeAlmanac does not need MCP to be useful. The connection is practical: once your repo has a curated local wiki, you may want an agent to read that wiki through a narrow, read-only MCP server rather than giving it the whole filesystem.

Use this as a small mcp training exercise, not as a grand integration. The goal is to practice a safe context boundary.

Prerequisites:

• A small repo where CodeAlmanac is already writing Markdown, or where you have copied a few wiki notes into docs/codealmanac for a test.
• A Codex workflow where repo rules live in AGENTS.md.
• An MCP-capable client setup.
• A willingness to keep the first server read-only.

1. Step 1: choose the smallest wiki path. Point the server at a narrow folder such as docs/codealmanac, not at the repo root. The first boundary should answer one question: “Can the agent read durable wiki notes?”

2. Step 2: add the MCP server config. Client config formats vary, so treat this as the shape of the setup, not a universal filename. The important part is the path boundary.

{
  "mcpServers": {
    "codebase-wiki-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "./docs/codealmanac"
      ],
      "env": {}
    }
  }
}

3. Step 3: write the boundary in AGENTS.md. Put the human rule next to the repo rules so Codex has the same constraint every run.

# AGENTS.md

## Codebase wiki context

Use the CodeAlmanac wiki as read-only background context.
Prefer source files, tests, and current task instructions when they disagree.
Do not edit wiki files unless the task explicitly asks for a documentation update.
When you use a wiki note, mention which decision or invariant it affected in the final response.

4. Step 4: ask for a narrow task. Use a task that should benefit from remembered context, such as “trace the refund retry path and explain what invariant protects duplicate refunds.” Avoid broad “understand the repo” prompts; they invite context soup.

5. Step 5: verify the setup worked. The proof is not that the agent read a file. The proof is that it cites a specific wiki decision, checks it against current code, and avoids a mistake it made before.

Copy this try-it-safely checklist

Use this checklist before letting any generated wiki become part of your normal Codex loop.

• Start with one repo and one wiki folder.
• Confirm CodeAlmanac output is plain Markdown committed through Git.
• Review the first three wiki changes like code review, not like notes.
• Delete summaries that only restate a transcript.
• Keep decisions, invariants, workflows, and gotchas.
• Add an AGENTS.md rule that says wiki context is advisory, not authoritative.
• If exposing the wiki through MCP, expose a read-only folder first.
• Run one repeat-bug test: ask the agent to handle a task it previously got wrong.
• Keep the experiment if the wiki prevents a real repeat or shortens a real explanation.
• Stop if the wiki becomes stale faster than humans review it.

The checklist is intentionally small. The point is not to build a documentation bureaucracy. The point is to find out whether your agent conversations contain reusable knowledge worth saving.

Common questions

• Does CodeAlmanac prove better outputs or token savings?

  No public benchmark in the repository proves better outputs or token savings. The repo describes a local workflow and background jobs, not an eval suite. A fair test is to choose one repeated failure mode, let CodeAlmanac capture the relevant context, and compare the next Codex run against the old mistake.

• Is CodeAlmanac Mac-only?

  Yes, the README says CodeAlmanac supports macOS today with Codex or Claude Code. The setup uses three local macOS launchd jobs for sync, garden, and update work. The idea is not inherently macOS-only, but the current implementation should be treated as macOS-first until other schedulers are supported.

• Should mcp training start with a read-only mcp server?

  Yes. A read-only mcp server is the safest first exercise because it teaches the boundary without giving the agent write access. For a CodeAlmanac-style wiki, expose only the Markdown wiki folder, then verify that the agent uses a specific note and checks it against current source code.

• Can I use CodeAlmanac for production workflows beyond dev work?

  Maybe, but only if those workflows can be represented as reviewed repo knowledge. CodeAlmanac is aimed at codebase context for coding agents, not general operations documentation. If production runbooks, incident invariants, or release gotchas live beside code and are reviewed in Git, the pattern may transfer.

• What is MCP, and why does it matter here?

  MCP is the Model Context Protocol, a standard for connecting AI clients to external tools and data through servers. It matters here because durable wiki context becomes more useful when agents can access it through a small, auditable boundary instead of receiving a giant pasted prompt.

Best ways to use this research

• Best for: Codex users who already see agents repeat old architectural mistakes and want a local, reviewable memory layer.
• Best first artifact: One AGENTS.md rule plus one reviewed CodeAlmanac wiki folder, not a repo-wide context expansion.
• Best comparison angle: Compare CodeAlmanac against your current manual docs habit: MANUAL.md, design notes, review comments, and repeated prompt boilerplate.
• Best safety test: Ask the agent to solve a task it previously mishandled, then check whether the wiki changed the reasoning, not just the wording.

Further reading

• codealmanac — source
• Model Context Protocol — specification
• OpenAI Codex — documentation
• OWASP — Top 10 for Large Language Model Applications

Next step

Pick one repo where agents keep forgetting the same thing, and try CodeAlmanac on that narrow slice. Keep it only if the first reviewed wiki notes make the next Codex run measurably less repetitive.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.