codealmanac

your repository. It contains connected Markdown pages that cover things not documented in the codebase, including decisions you have made and why the codebase is shaped this way. The pages are indexed in SQLite and are queryable through a CLI. We add instructions to AGENTS.md or CLAUDE.md so future sessions automatically search the wiki before they start coding. Every five hours, CodeAlmanac uses the Codex/CC SDK to spin up an agent that reads your new conversations and updates the relevant pages. We went with a time-based trigger instead of commits because we saw people commit very frequently, which would lead to high token costs. We originally made CodeAlmanac for individual developers, but the team use case has become much more obvious to us while using it ourselves. We are a team of three, and each of us works with our own coding agents. Before this, I would make some change after a lot of thinking and then later have to call my cofounders and explain why it looked this way. There is almost a sense of relief now knowing that the decisions I made are written down somewhere their agents will actually read. It’s live today for everyone to try. Please let me know your feedback and I’ll be here to answer any questions. Would also love to hear how you all maintain context across conversations today!

o develop on this platform. I think wikis are a much better way of giving your agent access to quality information compared to RAG. So there is also a Python SDK as well as an MCP that you can use to build on top of it. The project is still early, and I would love any feedback or feature requests that you have. Btw we've also made an open-source version of Almanac for code called CodeAlmanac(https://github.com/AlmanacCode/codealmanac)

what ideas you’ve explicitly rejected, and repeatable procedures that the agent did. We document what’s relevant for future agent runs from there. Maintenance, maintenance, maintenance: An organised wiki is a queryable wiki. Since the first wiki, WikiWikiWeb, people have talked about the need for wiki gardening (see: https://wiki.c2.com/?WikiGardener=). In CodeAlmanac, an agent gardens your wiki every few hours. Docs as code: The wiki lives in your repository as a folder, following the docs as code philosophy See: https://www.writethedocs.org/guide/docs-as-code/ Frequent updates: An outdated wiki is worse than no wiki (see: https://www.trevorlasn.com/blog/outdated-docs-are-tech-debt ). Almanac updates the wiki every 5 hours, and the time between updates is configurable. What goes in the wiki We have borrowed heavily from the Diataxis framework(https://diataxis.fr/). Here’s some of the things the wiki covers: How-to guides (AKA Skills): These cover repeatable procedures and explain things step by step to the agent (eg., How to deploy the CLI, see: https://git.new/2uKhYr7 . They function much the same way as skills, but are connected to the rest of the knowledge base. I talk more about why we think skills are the wrong abstraction here. Decisions: In every conversation with your agent, you make many important decisions. Almanac saves these inside the decisions folder. For example, our pipeline doesn’t commit code directly and instead lets the underlying model do it. This was automatically documented here: https://git.new/6M6Cprw Architecture: Every time you start a new run, your agent needs to read and piece together the codebase. This burns tokens unnecessarily, especially on large codebases. We maintain docs on the entire architecture so it can read only what’s relevant: https://git.new/FJQdHVh. Would love to hear your feedback and any feature requests! Check it out here: https://github.com/AlmanacCode/codealmanac/ (We only support macOS right now, but are working to support Linux/Windows)