gitmark

GitMark Memory Bank

A project knowledge base is just markdown + a README index + git. Nothing simpler works better.

Above: the actual documentation graph of a live production project (hub.neuraldeep.ru) — generated by gitmark map, gravity mode on. Colors = services. This isn't a mockup; it's a KB being used and evolved daily.

---

The idea

Markdown is the source of truth — the thing you and your AI assistant read directly, in any editor. Everything derived (a search index, this HTML overview, the link graph) is regenerated from the md, so git stays clean. No service, no database, no embeddings, no vendor. The entry point is CLAUDE.md / AGENTS.md; every folder's README.md is its index.

CLAUDE.md / AGENTS.md      ← entry point
/docs
  README.md                ← master index
  /services
    /<service>
      README.md            ← always the folder index

Battle-tested over months of building with AI assistants. The KB an agent (and a human) actually wants is plain md you can read anywhere — plus instant search so you find the right file instead of grepping blind.

What's in here

gitmark — one self-contained Python-stdlib CLI, zero dependencies:

command	what
index	build a SQLite FTS5 index: bm25 ∪ trigram (substring) ∪ fuzzy (4-char windows, typo/morphology/non-Latin tolerant)
search	ranked file:line · heading · snippet; --json for tooling
map	self-contained HTML: collapsible tree + rendered markdown + a force/radial graph of links
serve	tiny local HTTP server to view the map
stat	index/KB stats
lint	(optional) ontology checks: broken links, frontmatter, folder READMEs
version	—

Plus a Claude Code plugin: skills kb-search + kb-curate and a /kb command, so the agent searches the KB instead of grepping, and follows light curation rules when editing.

Quickstart

python3 skills/kb-search/gitmark.py index            # build .gitmark/index.db
python3 skills/kb-search/gitmark.py search "auth flow"
python3 skills/kb-search/gitmark.py map -o docs-map.html && open docs-map.html

Pure python3 (≥3.7) with SQLite FTS5; the trigram tokenizer (SQLite ≥ 3.34) adds fuzzy/substring/non-Latin matching — detected automatically, degrades gracefully. Add .gitmark/ to .gitignore — it's a build artifact.

Install as a Claude Code plugin

/plugin marketplace add vakovalskii/gitmark-memory-bank
/plugin install gitmark@gitmark-marketplace

Or just copy skills/ and commands/ into your repo's .claude/ — project-local, no marketplace needed.

Optional: the ontology (only if you want guardrails)

The simple core needs no frontmatter at all — index/search/map work on raw markdown. If a team wants the KB not to rot as it grows, there's a light code-ontology (inspired by Palantir's Ontology): each doc gets a node_type, a few frontmatter properties, and typed links — and gitmark lint enforces it (no broken links, no orphans, every folder has a README index). See docs/ontology.md. Use it or ignore it; the tool doesn't force it.

Why this and not a wiki / Notion / vector-DB memory

Because the simplest thing wins: md you already read, git you already use, one stdlib file you can audit in an afternoon. It runs offline, leaks nothing to a SaaS, and you own every byte. There are a thousand "memory banks" — this one's bet is radical simplicity that you can watch working on a real product, not another service to run.

License

MIT — see LICENSE.