README
¶
Katalyst
[!WARNING] Katalyst is in its earliest days. I'm actively building it in the open, which means things are incomplete, rough in places, and likely to change without notice. APIs, commands, config formats, and concepts can all break between commits. Please don't rely on it for anything important yet. If you have feedback, open an issue, or open a pull request if you have a fix.
Katalyst is a content consistency layer, designed for people and agents who curate persistent memory, wikis, and knowledge bases.
Katalyst gives you and your agent tools to solve problems like these:
- "My agent takes a long time to find things, and sometimes burns a ton of tokens."
- "I've repeatedly told my agent how to organize content and it still gets it wrong."
- "Sometimes when I go back and look, I discover that my agent has completely lost important information."
- "The content in my knowledge base isn't just text. It also includes metadata that I need to be able to categorize, score, filter, sort, etc."
- "My agent is supposed to store and curate notes for me, but I spend way too much time checking its work."
- "I want to change how I'm storing my data, but migration would be a big pain."
If you want to be confident that your content/data/memory is always in good shape, even when it's maintained by sometimes-sloppy agents and sometimes-sloppy humans, then Katalyst is for you.
Need a quick shape profile of an existing wiki before authoring rules? Use
katalyst inspect <path> to report frontmatter, markdown, and filename
conventions as evidence, and, once you've configured collections,
katalyst inspect <collection> to profile a collection's items. The full
command surface (including inspect) is in the
command reference.
[!TIP] New to Katalyst? Get started »: install the CLI, scaffold a
.katalyst/project, and run your first checks in a few minutes.
Key features
Catalog the content you already have
Katalyst comes with tools and skills to take stock of your content, no matter what state it's in today. It can help you (and your agents) figure out what you've got, map out the important concepts, and, if needed, get more organized.
Compared to having an LLM scan every file or write its own bash scripts, this approach can save a ton of tokens. It also lets you take advantage of skills, tools and strategies curated by a community of people who've faced similar challenges.
Define the language and structure that work best for you
Curation always requires shared language and consistent structure. Katalyst provides tools for declaring structure and rules for your content in your knowledge base.
- Markdown content: required sections, naming conventions, templates, etc.
- File structure: naming conventions, preferred and required extensions, directory structures, etc.
- Metadata: required fields, types, enums, numeric ranges, and full JSON Schema validation of frontmatter.
- Object relationships: links, summaries, tables of contents, sequential numbering, etc.
Reshape as needed
As your content evolves, Katalyst gives you tools to navigate change.
- Add or change checks
- Change the structure of your content
- Change your base
Design principles
Lightweight, deployable anywhere
You can run Katalyst as a linter, a CLI, or a server. Use only the infrastructure that you need for your particular use case.
Model- and backend-agnostic
I'm building Katalyst to work with a variety of filesystems and databases. It isn't tied to any one data store.
Similarly, you choose which model to use.
Leans into shared language
Express the same rules in a project's own vocabulary and conventions.
Built for both humans and agents
Ergonomics matter: especially for agents. An agent should be able to read the rules, find what it needs, and extend them without ceremony:
- Speed: fast enough to run on every write.
- Discoverability: an agent can find the schemas and structure on its own.
- Readability: rules and content stay legible to humans and agents alike.
- Extensibility: add new check types as needs grow.
What if structure was light?
Curating your content with the right structure makes it more useful, but it also takes work. Historically, defining the right structure for knowledge was heavy: high-cost, high-risk, and sometimes technically demanding. This was doubly true when changing needs required updates to structure.
As a result, most structured data systems were rigid and hard to change. Most unstructured knowledge bases were either chronically outdated, or very limited in scope.
As AI starts to infuse our work, curating knowledge is going to become even more important, a massive potential unlock for people who want to work more productively and creatively with agents.
What if structure were light: easy to add, easy to maintain, easy to change?
In a world of unbounded creative collaboration with agents, the limiting factor isn't generating new ideas or gathering more information: it's having a shared language and structure to organize what we've learned, and to act on it together.
Installation
Install the latest release with Go (1.25+):
go install github.com/abegong/katalyst@latest
Or build from source:
git clone https://github.com/abegong/katalyst.git
cd katalyst
make build # produces ./katalyst
Then point it at a directory to profile its structure:
katalyst inspect ./my-knowledge-base
Skills for agents
Katalyst ships a family of skills that
teach a Claude/Cowork agent to drive the CLI — cataloging content, defining
collections and schemas, and deploying enforcement. Each is attached to a GitHub
Release as a .skill you install through your client's "Save skill" flow; no
clone required. Maintainers package them from source with make skills (writing
bin/*.skill); make skill SKILL=<name> packages one.
No, really, you should try it out
- Build the CLI and run your first checks.
- Contribute: dev setup, plus how we plan and document changes.
About me
I'm Abe Gong, a technical founder with a deep love for data/ML/AI and open source. I'm the co-creator of Great Expectations, the leading open-source tool for data quality.
I'm fascinated by AI and the way it's changing how we work and collaborate, and I'm building Katalyst in the open to explore it. I take user feedback seriously: open an issue for bugs, questions, or requests, or open a pull request if you have a concrete fix.
More about me: LinkedIn · twitter/x · personal site.
License
Katalyst is licensed under the Apache License 2.0.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd contains the cobra command tree for the katalyst CLI.
|
Package cmd contains the cobra command tree for the katalyst CLI. |
|
gendocs
command
Command gendocs renders the check-type reference under docs/reference/check-types/ from the check descriptors in internal/checks/registry.go, and the inspector reference under docs/reference/inspectors/ from internal/inspect/registry.go.
|
Command gendocs renders the check-type reference under docs/reference/check-types/ from the check descriptors in internal/checks/registry.go, and the inspector reference under docs/reference/inspectors/ from internal/inspect/registry.go. |
|
skillpack
command
Command skillpack packages the product skills under skills/ into .skill archives (one zip per shippable skill, SKILL.md at the archive root, the shared bootstrap bundled in).
|
Command skillpack packages the product skills under skills/ into .skill archives (one zip per shippable skill, SKILL.md at the archive root, the shared bootstrap bundled in). |
|
internal
|
|
|
checks
Package checks is the core of the check engine: the shared types every check type is built on (Context, Check, CollectionCheck, Violation) plus the registry that check types self-register with.
|
Package checks is the core of the check engine: the shared types every check type is built on (Context, Check, CollectionCheck, Violation) plus the registry that check types self-register with. |
|
checks/all
Package all blank-imports every check-type family so their init() functions register with the core checks registry.
|
Package all blank-imports every check-type family so their init() functions register with the core checks registry. |
|
checks/argcheck
Package argcheck holds generic validators that check-type parsers use to produce uniform error phrasing without a central per-kind switch.
|
Package argcheck holds generic validators that check-type parsers use to produce uniform error phrasing without a central per-kind switch. |
|
checks/checktest
Package checktest holds tiny shared helpers for the check-type family test suites, so each family package can test its checks without redefining common document and context setup.
|
Package checktest holds tiny shared helpers for the check-type family test suites, so each family package can test its checks without redefining common document and context setup. |
|
checks/filesystem
Package filesystem holds the check types that validate filename and path conventions for items, plus the collection-scoped filesystem checks (unique_filename, index_file_required).
|
Package filesystem holds the check types that validate filename and path conventions for items, plus the collection-scoped filesystem checks (unique_filename, index_file_required). |
|
checks/jsonschema
Package jsonschema is the JSON Schema check library: the first schema-backed CheckLibrary.
|
Package jsonschema is the JSON Schema check library: the first schema-backed CheckLibrary. |
|
checks/markdownbodytext
Package markdownbodytext holds the check types that validate relationships between frontmatter metadata and markdown body content (headings, sections, code fences).
|
Package markdownbodytext holds the check types that validate relationships between frontmatter metadata and markdown body content (headings, sections, code fences). |
|
checks/plaintext
Package plaintext holds the check types that validate body content as raw text, independent of markdown structure (requires, forbids, denylist).
|
Package plaintext holds the check types that validate body content as raw text, independent of markdown structure (requires, forbids, denylist). |
|
checks/structuredobject
Package structuredobject holds the check types that validate structured frontmatter fields: schema validation and the field-shape checks.
|
Package structuredobject holds the check types that validate structured frontmatter fields: schema validation and the field-shape checks. |
|
codec/markdownbodytext
Package markdownbodytext parses and encodes markdown body text with optional structured frontmatter.
|
Package markdownbodytext parses and encodes markdown body text with optional structured frontmatter. |
|
examples
Package examples is the registry of worked examples: small input corpora paired with a `katalyst` command.
|
Package examples is the registry of worked examples: small input corpora paired with a `katalyst` command. |
|
fix
Package fix is the transform engine for `katalyst fix`: given an item's content and its collection, it computes the canonical, fixed form.
|
Package fix is the transform engine for `katalyst fix`: given an item's content and its collection, it computes the canonical, fixed form. |
|
inspect
Package inspect profiles content and returns evidence, the descriptive dual of internal/checks: a check asserts a predicate; an inspector reports the distribution that predicate would be tested against.
|
Package inspect profiles content and returns evidence, the descriptive dual of internal/checks: a check asserts a predicate; an inspector reports the distribution that predicate would be tested against. |
|
project
loader.go holds the project loader: it reads a project's .katalyst/ directory and answers two questions:
|
loader.go holds the project loader: it reads a project's .katalyst/ directory and answers two questions: |
|
project/projecttest
Package projecttest holds shared test helpers for constructing temporary Katalyst projects.
|
Package projecttest holds shared test helpers for constructing temporary Katalyst projects. |
|
skillpack
Package skillpack packages the product skills under skills/ into .skill archives for distribution.
|
Package skillpack packages the product skills under skills/ into .skill archives for distribution. |
|
storage
Package storage is the seam between a backend store and the katalyst domain model, issue #31's "narrow interface."
|
Package storage is the seam between a backend store and the katalyst domain model, issue #31's "narrow interface." |
|
storage/collection
Package collection is the backend-neutral contract for reading a collection's items from a storage backend: the CollectionDefinition interface and the thin Item it yields.
|
Package collection is the backend-neutral contract for reading a collection's items from a storage backend: the CollectionDefinition interface and the thin Item it yields. |
|
storage/collection/filesystem
Package filesystem is the filesystem backend's CollectionDefinition: it maps a directory tree onto collections of markdown files (one file is one item, its id the filename stem) and persists item writes.
|
Package filesystem is the filesystem backend's CollectionDefinition: it maps a directory tree onto collections of markdown files (one file is one item, its id the filename stem) and persists item writes. |
|
storage/collection/listing
Package listing runs the `item list` filter/grep/sort/skip/limit pipeline over in-memory records.
|
Package listing runs the `item list` filter/grep/sort/skip/limit pipeline over in-memory records. |
|
storage/collection/predicate
Package predicate parses and evaluates metadata predicates used by collection variants and listing filters.
|
Package predicate parses and evaluates metadata predicates used by collection variants and listing filters. |
|
storage/collection/sqlite
Package sqlite maps one SQLite table to one Katalyst collection: each row is one item, the configured id column is the item id, and configured column captures become item attributes.
|
Package sqlite maps one SQLite table to one Katalyst collection: each row is one item, the configured id column is the item id, and configured column captures become item attributes. |