The problem

Your AI agents start from zero every morning.

Every new session, every new repo, every new teammate — the knowledge walks out the door. Kluris fixes that.

Your agents forget.

A new context window means a new brain. Every morning, every session, your agent re-learns your codebase from scratch.

Your best engineer leaves.

When the senior dev who knows why things are built this way moves on, their context leaves with them. A year later, nobody can explain the auth flow.

Your docs are for humans.

Wikis, Notion, and CLAUDE.md are written for people, not agents. They can't be searched, linked, or reasoned across by your AI.

Kluris gives every agent on your team a shared brain they read, search, and grow together.

Step 1

Install in two commands.

Kluris is a Python CLI distributed on PyPI. Install with pipx — it keeps things isolated and always up to date.

macOS

$ brew install pipx
$ pipx ensurepath
$ pipx install kluris

Linux

$ python3 -m pip install --user pipx
$ pipx ensurepath
$ pipx install kluris

Windows

> pip install pipx
> pipx ensurepath
> pipx install kluris

Verify the install

$ kluris doctor
  ✓ git found
  ✓ Python 3.11 found
  ✓ kluris 1.0.0 ready
  ✓ 8 agents detected (claude, cursor, windsurf, ...)

Everything looks good. You are ready to create a brain.

Step 2

Create your first brain for your new SME.

One command, one wizard, one git repo. You pick the name, the type, and the location — kluris does the rest.

kluris create — interactive wizard

$ kluris create

Brain name: acme-brain
Brain type:
  [1] product-group  [2] personal
  [3] product        [4] research
  [5] blank
Choice: 1
Location: ~/Projects/acme-brain
Initialize git? y
Register as default? y

  ✓ Created acme-brain
  ✓ Git initialized on main
  ✓ Registered as default brain
  ✓ Installed /kluris skill for 8 agents

Next: cd into any project and use
      /kluris learn this service

The folder kluris just created

acme-brain/
├── kluris.yml              # gitignored — your local config
├── brain.md                # root directory, auto-generated
├── glossary.md             # domain terms, hand-edited
├── README.md               # usage guide
├── .gitignore
├── projects/
│   ├── map.md              # lobe index, auto-generated
│   └── (your neurons go here)
├── infrastructure/
│   ├── map.md
│   └── (your neurons go here)
└── knowledge/
    ├── map.md
    └── (your neurons go here)

Every brain is a git repo. Your knowledge is markdown. Nothing is magic.

Anatomy

What lives inside a brain.

Seven pieces. Learn them once, use them forever.

Root

Brain

The top-level git repo. One brain = one shared knowledge base. You can have many.

Region

Lobe

A folder inside the brain. Each lobe is a knowledge region — projects, infrastructure, knowledge, tasks, whatever you need.

Atom

Neuron

A single markdown file inside a lobe. One idea, one decision, one runbook, one fact. Named with kebab-case.

Link

Synapse

A bidirectional link between two neurons. Written in frontmatter as related:. Dream auto-fixes one-way synapses into two-way.

Index

Map

An auto-generated map.md at the root of every lobe. Lists every neuron in the lobe. You never write this — dream writes it.

Vocab

Glossary

A single hand-edited glossary.md at the root. Defines your domain vocabulary so agents know what your team words mean.

Local config

kluris.yml

Your local config for this brain. Gitignored. Contains your git branch preference, your default commit prefix, and which AI agents you use. Each teammate has their own kluris.yml — so everyone can have different settings without touching the shared brain.

name: acme-brain
description: platform brains
git:
  default_branch: main
  commit_prefix: "brain:"

Teach

Teach the brain.

Three ways to write knowledge into a brain — all collaborative, all reviewed by you before anything is saved.

/kluris learn

Let the agent analyze your code.

Point the agent at a folder. It reads your code and proposes neurons one at a time, with a preview of every piece before it is written.

→Approve, edit, skip, or change the target lobe
→Nothing is written without your sign-off
→The agent infers related neurons automatically

> /kluris learn the auth flow

Analyzing src/auth/... (14 files)

Proposing neuron: projects/btb-core/auth-flow.md
──────────────────────────────────────
# Auth flow

We use Keycloak OIDC. Frontend obtains
JWT via Keycloak, passes it to backend
as Bearer token. Backend validates via
JWKS. Refresh at 80% TTL.

Related: [clerk-vs-keycloak.md,
          jwt-rotation.md]
──────────────────────────────────────

[a]pprove  [e]dit  [s]kip  [c]hange lobe:

> /kluris remember we chose raw SQL
                      over JPA for query
                      complexity

Proposing: knowledge/use-raw-sql.md
(template: decision)
──────────────────────────────────────
# Use raw SQL over JPA

## Context
Query complexity and performance
on the reporting endpoints...

## Decision
Use NamedParameterJdbcTemplate with
explicit raw SQL...

## Consequences
Less ORM magic, more typing, faster
queries, clearer SQL in git diffs.
──────────────────────────────────────

[a]pprove  [e]dit  [s]kip:

/kluris remember

Capture a decision in one line.

For when you just made a call and want to write it down before you forget. The agent turns your one-liner into a properly structured neuron.

→Auto-selects the decision template
→Fills in context, decision, consequences
→You edit or approve before anything lands

kluris neuron

Create one manually with a template.

When you want full control. Pick a template — decision, incident, or runbook — and get a pre-structured neuron to fill in by hand.

→Three built-in templates, ready to use
→Write your own templates too
→Dream automatically updates the lobe map

$ kluris neuron outage-jan.md \
    --lobe knowledge \
    --template incident

Created: knowledge/outage-jan.md
Template: incident

Sections:
  Summary
  Timeline
  Root cause
  Impact
  Resolution
  Lessons learned

Open it in your editor to fill in
the details. Run `kluris dream` to
refresh the lobe map afterward.

Ask

Ask the brain.

Once your brain has knowledge, every agent can use it. Search, query, and implement — all with your team's conventions baked in.

SEARCH semantic + keyword lookup

> /kluris search auth flow

Found 3 neurons:
  projects/btb-core/auth-flow.md       ★★★
  knowledge/jwt-rotation.md            ★★
  infrastructure/keycloak-setup.md     ★

Run `/kluris open auth-flow.md` to read one.

ASK natural language Q&A across the brain

> /kluris what do we know about Docker?

Reading:
  infrastructure/docker-builds.md
  infrastructure/environments.md

You build multi-stage Dockerfiles with
BuildKit. Images go to ghcr.io/zeespire/.
Prod uses Coolify on Hetzner with Cloudflare
Tunnel (zero public ports).

IMPLEMENT agent writes code using your conventions

> /kluris implement the POST /users
          endpoint following our conventions

Reading brain:
  - use-raw-sql.md (decision)
  - api-conventions.md
  - auth-flow.md

Generated endpoint using NamedParameter
JdbcTemplate, JWT validation, i18n JSONB
fields, explicit constraint names.

FIX bug fixes grounded in your brain

> /kluris fix the token refresh --
          use brain knowledge

Checking brain for auth decisions...
Found: knowledge/jwt-rotation.md

Conflict: your code refreshes on 401,
but the brain says refresh at 80% TTL.
Applying the brain's rule.

Operate

Three commands that keep your brain alive.

wake-up · dream · mri — the rituals of a healthy brain. Run them daily, weekly, or never — your choice.

WAKE-UP

$ kluris wake-up

Brain: acme-brain (default)
  Path: ~/Projects/acme-brain

Lobes (3)
  - projects/:        12 neurons
  - infrastructure/:   4 neurons
  - knowledge/:        7 neurons

Total neurons: 23

Recently updated (5)
  2026-04-05 use-raw-sql.md
  2026-04-04 auth-flow.md
  2026-04-04 docker-builds.md
  2026-04-02 state.md
  2026-04-01 import.md

Compact snapshot — agents run this on every new session.

DREAM

$ kluris dream

acme-brain health report:
  Lobes: projects, infrastructure,
          knowledge
  Maps regenerated: 4
  OK   synapses
  OK   bidirectional
  OK   orphans
  OK   frontmatter
  OK   deprecation
  6    automatic fixes applied
  3    dates refreshed from git
  1    missing parent inferred
  2    reverse links added

Brain is healthy.

Regenerates maps, validates synapses, refreshes dates from git.

MRI

$ kluris mri --open

MRI complete — brain-mri.html
  23 nodes, 31 edges
  → opening in browser

Interactive features:
  · search any neuron
  · hover to see connections
  · click to inspect content
  · pan and zoom the graph
  · filter by lobe

Share the HTML — it runs anywhere.

Interactive HTML visualization — nodes, edges, search, inspector.

A real kluris mri output — nodes are neurons, colors are lobes, dashed lines are synapses

Live output: an actual kluris mri of a real brain. Colors are lobes, dashed cyan lines are synapses, labeled nodes are neurons.

Customize

Shape your brain, your way.

Brains are not fixed. Add lobes, edit the glossary, write your own templates, deprecate old decisions — all with simple commands.

+

Add new lobes as you grow

Your brain evolves with your team. Add a new knowledge region in one command, or nest a sub-lobe inside an existing one.

$ kluris lobe analytics
Created: acme-brain/analytics/

$ kluris lobe post-auth \
    --parent projects/api/endpoints
Created: projects/api/endpoints/post-auth/

A

Edit the glossary by hand

Define the vocabulary your team uses in one file. Every agent on your team reads it and stops asking "what does that mean?"

# Glossary

**Neuron** — a single knowledge file
**Lobe** — a knowledge region folder
**Tenant** — a customer company
  in our multi-tenant SaaS
**Protocol** — our psychometric
  evaluation workflow

T

List and use built-in templates

Three templates out of the box — decision, incident, runbook. Each one has the right sections so your neurons are consistent.

$ kluris templates

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

×

Deprecate old decisions cleanly

Decisions change. Mark a neuron as deprecated instead of deleting it — history stays, and agents follow the replacement.

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

# Kluris dream will surface warnings
# for any active links to this neuron.

Switch

Run more than one brain.

A work brain, a personal brain, a team brain you cloned from GitHub — kluris keeps them separate and lets you switch in one command.

juggling three brains at once

$ kluris list
  acme-brain     (default)   ~/Projects/acme-brain       [git]
  personal                    ~/Projects/personal-brain   [git]
  research                    ~/Projects/research-brain   [no git]

$ kluris use personal
Default brain: personal
  ✓ /kluris skill updated for 8 agents

$ kluris status
personal (personal)
  Lobes: 3, Neurons: 18
  2026-04-05  tasks/today.md
  2026-04-04  notes/q2-goals.md

$ kluris clone git@github.com:acme/team-brain.git
  Cloning into ~/Projects/team-brain...
  ✓ Registered team-brain
  ✓ /kluris skill updated

Clone a team brain Switch in one command Keep work and personal separate Every brain has its own git history

Reference

Every command, one page.

Seventeen CLI commands, plus the /kluris agent patterns. Everything you need, nothing you don't.

CLI commands · kluris *

create	Create a brain (interactive wizard)
clone <url>	Clone a brain from git
list	List registered brains
use <name>	Switch the default brain
status	Show brain tree and recent changes
wake-up	Compact snapshot for agent bootstrap
neuron <file>	Create a neuron (--lobe, --template)
lobe <name>	Create a lobe (--parent for nesting)
dream	Regenerate maps, fix links, validate
push	Commit and push brain changes
mri	Generate interactive HTML viz
templates	List neuron templates
install-skills	Install /kluris skill for agents
uninstall-skills	Remove /kluris skill
remove <name>	Unregister a brain (keeps files)
doctor	Check prerequisites
help	Show command help

All CLI commands support --json for machine-readable output.

Agent patterns · /kluris ...

/kluris learn <topic>	Agent analyzes code, proposes neurons
/kluris remember <fact>	Quick-capture a decision as a neuron
/kluris search <term>	Search the brain for a topic
/kluris what do we know about ...	Ask the brain a question
/kluris implement <task>	Implement following brain conventions
/kluris fix <bug>	Fix a bug using brain knowledge
/kluris create a decision	Create a decision record neuron
/kluris create an incident	Create an incident report neuron
/kluris create a runbook	Create a runbook neuron
/kluris open <file>	Open a neuron and read it
/kluris deprecate <file>	Mark a neuron as deprecated

Agent patterns are free-form — say it naturally. The agent picks the template.

Your SME starts here.

Two commands. Free forever. Works with every AI agent on your team.

pipx install kluris View on GitHub

MIT licensed · Python 3.10+ · Works offline · All data is yours

Works with every agent on your team

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

The SME your team never had.