kluris 2.2.2

Turn your AI agents into team subject matter experts with shared, human-curated knowledge

Kluris

Turn your AI agents into team subject matter experts.

When your best engineer sleeps, Kluris doesn't. When they leave, Kluris stays.

What is Kluris?

Kluris gives every AI agent on your team shared knowledge -- architecture, decisions, conventions, learnings -- so they work like an SME who knows your entire codebase, not a generic assistant starting from scratch every time.

Knowledge is stored in a brain: a git-backed repo of structured markdown that agents read, search, and apply automatically. The human and agent curate the brain together -- the agent proposes what to document, the human reviews and approves every piece.

Why not a wiki, Notion, or CLAUDE.md?

• Wikis and Notion are for humans. Agents can't read them, search across them, or write back. A brain is markdown in git -- AI-native.
• CLAUDE.md is per-project and per-tool. A brain sits above all your projects and works with every AI agent on the team.
• Agent memory is agent-controlled -- the agent decides what to keep. A brain is human-curated -- you decide what goes in, review every entry, and correct anything that's wrong.

One brain serves all your projects. Every agent reads the same knowledge. Version-controlled, human-curated, shared across the entire team.

Install

macOS:

brew install pipx && pipx ensurepath

Linux:

python3 -m pip install --user pipx && pipx ensurepath

Windows:

pip install pipx && pipx ensurepath

Then restart your terminal and:

pipx install kluris

Quick start

kluris doctor        # check prerequisites
kluris create        # interactive wizard -- name, type, location, git

Then open any project directory and use /kluris:

/kluris learn everything about this service

The agent analyzes your code and walks you through each finding one at a time. You see a small preview before anything is written, and you approve, edit, or skip every piece.

How the agent bootstraps (automatic)

On the first /kluris call of a session, the agent runs kluris wake-up --json through its shell to load a compact snapshot of the brain: the brain.md body, lobes with neuron counts, the 5 most recently updated neurons, the full glossary, and any deprecation warnings. That's enough context for the agent to decode jargon and avoid citing superseded neurons without touching the filesystem again for the rest of the session. You never call it manually. The agent refreshes the snapshot after mutating commands (/kluris remember, /kluris learn, kluris neuron, kluris lobe, kluris dream, kluris push).

If you want to see what the agent sees, run it yourself:

kluris wake-up            # pretty text
kluris wake-up --json     # machine-readable
kluris wake-up --brain X  # target a specific brain when more than one is registered

Working with multiple brains

Each registered brain installs as its own slash command. With one brain registered, that command is /kluris. With two or more, each brain installs as /kluris-<name> (e.g. /kluris-acme, /kluris-personal). Every per-brain skill is bound to exactly one brain — the agent never has to guess which one you mean.

CLI commands prompt interactively when 2+ brains are registered:

• Fan-out commands (dream, push, status, mri) show [1] acme [2] personal [3] all. Pick a single brain or apply to every brain.
• Single-brain commands (wake-up, neuron, lobe) show [1] acme [2] personal (no all option).

Pass --brain NAME to skip the picker, or --brain all on fan-out commands to act on every brain at once. Scripts and CI must always pass --brain because non-TTY contexts disable the picker — set KLURIS_NO_PROMPT=1 to force non-interactive mode even from a TTY (useful for wrappers like Claude Code that inherit a terminal but cannot block on prompts).

Joining an existing brain

kluris clone [e-mail]:team/brain.git    # clone and register

Learning a project

Open any project directory and use /kluris -- the agent analyzes your code and walks you through each finding. You review, edit, and approve before anything is written.

/kluris learn the API endpoints and data model
/kluris learn the Docker and deployment setup
/kluris learn everything about this service

The agent starts with a preview before writing. You can change the target lobe, edit the content, add context the code doesn't show, or skip.

Storing decisions and knowledge

/kluris remember we chose raw SQL over JPA for query complexity
/kluris remember all timestamps must be TIMESTAMPTZ
/kluris create a decision record about the auth architecture
/kluris create an incident report for the January outage

Using brain knowledge while coding

/kluris search auth flow
/kluris search Docker setup
/kluris what do we know about the auth flow?
/kluris implement the new endpoint following our conventions
/kluris fix the token refresh -- use brain knowledge

The agent reads the brain first, then works on the task. If your code contradicts a documented decision, it flags the conflict.

Maintaining the brain

kluris dream         # regenerate maps, fix links, validate structure
kluris push          # commit and push to git (if brain uses git)
kluris status        # brain tree, neuron counts, recent changes
kluris mri --open    # generate and open in browser

Deprecating a decision

When a decision is superseded, mark the old neuron instead of deleting it -- the history is valuable. Add these optional frontmatter fields to the old neuron:

---
status: deprecated
deprecated_at: 2026-04-01
replaced_by: ./use-clerk.md
---

kluris dream reports four kinds of deprecation warnings (non-blocking):

• active_links_to_deprecated: an active neuron's related: points at a deprecated one -- update the link to point at the replacement.
• deprecated_without_replacement: a deprecated neuron has no replaced_by -- add one so readers have a migration path.
• replaced_by_missing: replaced_by points at a file that doesn't exist.
• replaced_by_not_active: replaced_by points at something that isn't an active neuron (another deprecated neuron, or a non-neuron file like map.md).

Agents see a deprecation_count summary via kluris wake-up and the full list via kluris dream --json. They flag affected topics when asked.

What a brain looks like

acme-brain/
├── kluris.yml              # Local config (gitignored -- your agents, branch)
├── brain.md                # Root lobes directory (auto-generated)
├── glossary.md             # Domain terms (hand-edited)
├── README.md               # Usage guide
├── projects/
│   ├── map.md              # Lobe index (auto-generated)
│   └── btb-core/
│       ├── map.md
│       ├── data-model.md   # <- neuron
│       └── auth-flow.md    # <- neuron
├── infrastructure/
│   ├── map.md
│   ├── docker-builds.md    # <- neuron
│   └── environments.md     # <- neuron
└── knowledge/
    ├── map.md
    └── use-raw-sql.md      # <- neuron (decision template)

Folders are lobes (knowledge regions). Files are neurons (knowledge units). Links between neurons are synapses. Auto-generated map.md files keep everything navigable.

Brain types (scaffolding only)

Types determine the initial folder structure. After creation, every brain works the same -- all templates and commands are available regardless of type. You can add or remove lobes freely after creation.

product-group (default)

For a group of projects/services that share knowledge. Example: a platform with 3 backends, a frontend, and shared infrastructure.

Lobe	What goes in it
projects/	Per-project sub-folders -- APIs, data models, setup, conventions
infrastructure/	Hosting, CI/CD, Docker, deployment, environments, env vars
knowledge/	Decisions, learnings, troubleshooting tips, domain expertise

The projects/ lobe nests deeper -- one sub-folder per project:

projects/
├── map.md
├── btb-core/
│   ├── map.md
│   ├── auth-flow.md
│   └── endpoints/
│       ├── map.md
│       └── post-auth-login.md
├── btb-frontend/
│   ├── map.md
│   └── state-management.md
└── btb-summon/
    └── map.md

Project neurons link to infrastructure neurons for deployment details and environments -- never duplicate infra content across lobes.

personal

For an individual developer's knowledge -- projects, tasks, and notes.

Lobe	What goes in it
projects/	Sub-folder per project: branches, status, TODOs
tasks/	Current priorities, blockers, in-progress work
notes/	Daily notes, ideas, learnings

product

For product management -- requirements, features, and user research.

Lobe	What goes in it
prd/	Requirements, user stories, acceptance criteria
features/	Sub-folder per feature: specs, status, feedback
ux/	User research, personas, journey maps, wireframes
analytics/	Metrics, KPIs, experiment results
competitors/	Competitive analysis, market positioning
decisions/	Product decisions and rationale

research

For research projects -- literature, experiments, and findings.

Lobe	What goes in it
literature/	Papers, articles, summaries, key findings
experiments/	Hypotheses, methodology, results
findings/	Synthesized insights, conclusions
datasets/	Data sources, schemas, access notes
tools/	Research tools, scripts, environments
questions/	Open questions, hypotheses to test

blank

Empty -- build your own structure from scratch.

How it works

1. kluris create -- create a brain (interactive wizard)
2. kluris install-skills -- give the /kluris skill to your AI agents
3. Open any project and use /kluris -- the agent becomes an SME
4. Agent and human curate the brain together -- you review and approve every entry
5. kluris dream -- maintain brain structure
6. kluris mri -- visualize the brain

CLI commands

Command	What it does
kluris create	Create a new brain (interactive wizard)
kluris clone <url>	Clone a brain from git
kluris list	List registered brains
kluris status	Brain tree, neuron counts, recent changes
kluris search <query>	Ranked search across neurons, glossary, brain.md (--lobe, --tag, --limit, --json)
kluris wake-up	Compact brain snapshot for agent session bootstrap — includes brain_md, glossary, deprecation (--json)
kluris neuron <name>	Create a neuron (optionally with --lobe and --template)
kluris lobe <name>	Create a new lobe (optionally with --parent for nesting)
kluris dream	Regenerate maps, fix links, validate structure
kluris push	Commit and push brain changes to git
kluris mri	Visualize the brain (opens in browser by default)
kluris templates	List available neuron templates
kluris install-skills	Install the /kluris (or /kluris-<name>) skill for your AI agents
kluris uninstall-skills	Remove all kluris skills from AI agent directories
kluris remove <name>	Unregister a brain (keeps files on disk)
kluris doctor	Check prerequisites AND refresh installed agent skills (run after pipx upgrade kluris). Pass --no-refresh to skip the refresh and run only the read-only checks.
kluris help	Show command help

All commands support --json for machine-readable output. The CLI is for mechanical operations; guided documentation happens through /kluris (or /kluris-<name>) inside your agent. Under the hood the agent calls kluris search for lookups and kluris wake-up for the session bootstrap.

Neuron templates

Available in every brain. Use kluris templates to see them.

Template	Sections
decision	Context, Decision, Rationale, Alternatives considered, Consequences
incident	Summary, Timeline, Root cause, Impact, Resolution, Lessons learned
runbook	Purpose, Prerequisites, Steps, Rollback, Contacts

Local config (kluris.yml)

Each brain has a kluris.yml that is gitignored -- it's your local config, not shared. Each team member can have different settings.

name: my-brain
description: my-brain knowledge base
git:
  default_branch: main
  commit_prefix: "brain:"

Brain vocabulary

Term	Meaning
Brain	Git repo of shared team knowledge
Lobe	Folder / knowledge region
Neuron	Single knowledge file
Synapse	Link between neurons (bidirectional)
Map	map.md -- auto-generated lobe index
MRI	Interactive brain visualization
Dream	Brain maintenance -- regenerate maps, update dates, auto-fix safe issues, validate remaining links

Supported agents

Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, Gemini CLI, Kilo Code, Junie

License

MIT