Artificial Intelligence/ ·4 min read
Building Almagest: One Truth in Every Product Manager's Context Window
AI /Side Project /Product Management /Knowledge Management /From My Desk
Almagest is an open-source knowledge base that a coding agent compiles and a person curates. You point it at your sources, the agent proposes wiki pages with every statement traced back to where it came from, contradictions between sources stop the run and ask, and nothing lands until someone has read the diff and merged it. The result is one place where the truth about a product lives, written so that both people and agents can read it.
The code is at github.com/oleharland/Almagest, MIT licensed. This is the product problem it answers.
Every tool, every contradiction
Take a product organisation with a dozen Product Managers. Over the last year most of them started prompting AI with their work, and the obvious next step was to give the agents access to the tools. MCP made that easy. Within weeks an agent could read the roadmap tool, the wiki, the ticket system, the strategy decks, and the meeting notes.
The answers got worse.
The reason took a while to see. The strategy deck from January named three company goals. The roadmap tool had five, two of them renamed since. A wiki page from last quarter described a pricing decision that had been reversed in a meeting nobody wrote up. Each of these was true on the day it was written, and every one of them was now reachable by an agent that had no way to know which one still held. Ask it about the priorities and it picked one, confidently, and built a plan on it.
Worse, it picked a different one for each person. Every Product Manager had a slightly different set of tools connected, a slightly different prompt, and a slightly different idea of what the goals were. The AI took that drift and gave it a fluent voice. Twelve people were now shipping twelve interpretations of the strategy, each backed by an agent that sounded certain.
Connecting more sources cannot fix this. Every new source is another version of the truth for the agent to choose from.
What was missing was a curated layer
What that organisation lacks is a single point of truth, and it has to be one that agents read first.
That layer has three properties, and none of them is technical.
Someone decided. When two sources disagree, a person looked at both and chose, and the choice is written down with the reasoning. The old goal is marked superseded. The reversed pricing decision points at the meeting that reversed it. An agent reading the layer inherits decisions instead of inheriting the argument.
Everything says where it came from. A goal in the layer names the deck and the slide. A number names the report and the page. When a Product Manager asks “where does this come from” the answer is a link, and when the deck changes the layer knows which pages it touched.
Unknowns are written down too. If no source says who owns a metric, the page says so under open questions. An agent that reads “we do not know” gives a better answer than one that reads nothing and fills the gap.
I had been running something like this for my own side projects, with an Obsidian vault as the context layer for a pipeline of Claude Code agents. It worked because one person curated it. The question was whether the same discipline could hold across a product org, with many hands and an agent doing most of the reading.
Curation is the product
Almagest is that discipline made into a workflow.
You drop a source into a folder, or point it at a repository. The agent reads it, checks what the wiki already knows about the entities in it, and proposes pages: a goal, a decision, a customer segment, a system, whatever page types you have configured for your domain. Every claim on a proposed page cites the source it came from.
When a new source contradicts an existing page, the agent does not write. It quotes both claims with their sources, recommends a resolution, and waits for a person. That is the moment curation happens, and the whole design exists to make sure it happens with a human in the seat. The same goes for anything touching a canonical page, which is the tier where the agreed goals and definitions live. The agent cannot edit those. Evidence that argues with them is logged to a challenges file where a person can see it, so a stale goal gets challenged in the open instead of overwritten by whichever source was ingested last.
Everything the agent does write goes to a branch, and the review is a diff. Reading a diff at the end of an ingest takes minutes. Reading it beats the alternative I started with, which was approving each page from the agent’s own summary of its own work, at the end of a long day, by typing y.
The part I did not plan for was how much the cross-linking would surface. Because every page lands in one wiki and the agent checks for existing entities before creating new ones, two initiatives that touch the same customer segment or the same metric end up linked whether or not their owners ever spoke. A search for a goal returns every decision, project, and open question that cites it. When the information sat in six tools, those overlaps were invisible. In one wiki they are the first thing you see.
What changes for a Product Manager
The immediate change is that everyone prompts from the same goals. The canonical pages are the first thing an agent reads in the repo, so a Product Manager asking for a prioritisation, a stakeholder update, or a draft PRD gets it against the company goals as they stand today, with the same wording their colleague gets.
The second change is that answers come with a trail. A number in a draft names its source. A recommendation that rests on inference says it is inference. When a Product Manager shares the output, the reviewer can check it instead of trusting it.
The third is that a Product Manager’s own conclusions have a place. A page can be marked as the author’s own thinking, with no citations, as long as it lists the sourced pages it rests on. The wiki holds what was decided and why, and an agent can tell the difference between a fact from a document and a call someone made.
The fourth change reaches past the product organisation. A goal, a decision, or a reversal made in a product team matters to the sales lead writing a proposal, the support team answering a customer, the engineer scoping the next quarter, and the marketing team drafting a launch. All of them prompt AI now, and most of them do it with whatever context their own tools hold. With the layer in place, their agents read it first as well, and the product organisation’s decisions become something anyone in the company can query, with the reasoning attached. Support stops quoting a price that was reversed in June. Sales stops promising a feature that was cut. The Product Manager stops being the only person who knows.
What it costs
Almagest optimises for trust in what the notes say and pays for it everywhere else.
Capture is slow. Ingest is a deliberate, reviewed step, and someone has to own the curation. If nobody resolves the contradictions the agent surfaces, the wiki stops growing, and that is by design. There is no mobile story and no inbox, because it is a git repository and a coding agent. It scales to thousands of pages with search, and no further; if you have forty thousand documents you want a retrieval system, and it will retrieve the contradictions along with everything else.
The program checks the plumbing: that every citation points at a real source, that every link resolves, that a source has not changed under a page. It cannot check that the source says what the page claims. That is the reviewer’s job, and it is the reason a person merges.
The name
It was called Codex for a day, until I remembered who else uses that name. Almagest is Ptolemy’s star catalogue: a canonical reference compiled from many earlier observations, each one credited to where it came from. That is what a product org needs its context to be.
If you run a team where several people prompt against the same product, I would like to hear how you keep their context aligned. The tool exists because I could not find an answer to that question that survived the second contradicting source.
