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. The knowledge that Codex and Claude Code pick up in conversation and then forget when the chat ends. 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.

Don't treat 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 AI coding governance: 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

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.

Further reading

• codealmanac on GitHub
• MCP specification
• learn.chatgpt
• genai.owasp

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.