Gitian

// topics mint themselves · relatedness shows its work

Your codebase, remembered.

Your agents publish what they learn over MCP. Topics mint themselves as they write. Relatedness is computed, weighted, and explained. You browse the graph, open any node, and diff what changed.

How topics work
  • described topic
  • stub topic
  • doc
  • memory
  • entry
  • explicit related

How the knowledge base is used

Search

The agent reads what earlier sessions settled before it touches a file.

Publish

A decision, a plan, a day's record. Three shapes, one required manifest.

Read back

You open it at a URL and diff it. The next session does the same.

// nodes

Three shapes, and the topics that connect them

An agent that can write anything writes inconsistently. Three primitives with a required manifest keep the corpus legible six months later. Topics are the fourth kind of node, and the agent never has to ask permission to make one.

doc

A long-form artifact with a lifecycle and a tracked manifest: status, files, commits, next_steps, blockers. A spec, a plan, a design, a handoff, a recap.

memory

One atomic, durable fact: a gotcha, a preference, a project fact. Named by what it states, ci-flaky-oauth-token, never note-1.

entry

A dated journal record for a scope, appended as events happen. One per scope and date; the slug is derived, never supplied.

topic

Named in frontmatter, minted that instant, live in relatedness from that moment. Describe it once and it reads as a real topic; a stub stays an outline until someone does.

Pick by shape, not by size. A multi-day effort with next steps is a doc even if the write-up is one paragraph. A fact that took three days to learn is still a memory.

// edges

Relatedness that shows its work

Two items are related by a weighted cosine over their shared topics, where a topic's weight is log(N / degree) / log(N): a topic linked to nearly everything trends toward zero, a rare one toward one. A hub topic can't make everything look related to everything. An explicit related entry or a body [[wikilink]] floors the pair at 1.0.

There are no stored edges. neighbors is a query-time two-hop traversal, so nothing goes stale and a call made right after a publish already reflects it. Unused topics decay on a half-life your own writing extends, and any new link revives one instantly. The full vocabulary rules.

// open any node

Read it. Diff it. Nothing is overwritten.

Every write lands as a document with a slug, a tracked manifest, and a URL. Revisions are append-only and every adjacent pair diffs, so you can read the moment a status flipped or a decision was rewritten. Deletion is a tombstone. The manifest keeps its nulls. And it survives /compact, because compaction discards conversation, not published records.

// the ground

The graph is what your agents learned. The repo is what the code says.

gitian renders both in one app, with the same Obsidian-flavored markdown. Add @gitian to a comment you already wrote and it becomes a browsable annotation. Drop a docs/ directory anywhere and files pair with their source by name.

Source
1
// @gitian Validates user input
2
export function validate(input) {
3
  // @gitian:todo Add rate limiting
4
  return input.isValid;
5
}
6
// @gitian:deprecated Use validate() instead
7
function check(v) { ... }
Rendered
@gitianValidates user input
export function validate(input) { ... }
Add rate limiting
@gitian:deprecatedUse validate() instead
function check(v) { ... }

Code annotations

Tag a comment with @gitian, or sub-tags like @gitian:todo and @gitian:deprecated. Existing @param and TODO comments are picked up too. The annotation reference.

docs/ pairing

docs/auth.ts.md documents auth.ts. A Docs tab beside the Source tab.

Wikilinks, callouts, Mermaid, KaTeX

Obsidian-flavored markdown, rendered from the repo. GitHub today; GitLab coming.

Directives, dashboard, PR analysis

Pull live annotations into markdown. A repo dashboard breaks them down; a PR comment reports what the diff did to them.

// begin

Two commands, then your browser.

The first tool call answers with a 401 that carries everything an OAuth-aware client needs. Consent happens in your browser; CI uses a gkb_ token, stored only as a hash. Every connection is listed and revocable under Connected agents. Transport and scopes.

Explore the demo repository
claude plugin marketplace add GitianDocs/gitian-tools
claude plugin install gitian-kb@gitian-tools

# first tool call → 401 → browser consent → done