Metadata-Version: 2.4
Name: kluris
Version: 2.2.8
Summary: Turn your AI agents into team subject matter experts with shared, human-curated knowledge
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: pydantic>=2.0
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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:**
```bash
brew install pipx && pipx ensurepath
```

**Linux:**
```bash
python3 -m pip install --user pipx && pipx ensurepath
```

**Windows:**
```bash
pip install pipx && pipx ensurepath
```

Then restart your terminal and:

```bash
pipx install kluris
```

## Quick start

```bash
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:

```bash
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

```bash
kluris clone git@github.com: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

```bash
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:

```yaml
---
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.

```yaml
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
