Metadata-Version: 2.4
Name: kluris
Version: 0.1.5
Summary: Create and manage git-backed AI brains for multi-project, multi-agent teams
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

> Create and manage git-backed AI brains for multi-project, multi-agent teams.

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

## What is Kluris?

Kluris is a CLI tool that creates **brains** — standalone git repos of
structured markdown that AI coding agents read, search, and update through
globally installed slash commands.

**Kluris = the tool. A brain = the git repo it creates.**

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

- **Wikis and Notion** are for humans. Agents can't natively read them, search
  across them, or write back. Kluris brains are markdown in git — AI-native.
- **CLAUDE.md** is per-project and per-tool. A brain sits above all your
  projects and works with 8 different AI agents simultaneously.
- **Agent memory** is session-scoped and ephemeral. A brain is persistent,
  version-controlled, and shared across the entire team.

One brain serves all your projects. Every AI agent on the team reads the same
knowledge. When someone leaves, nothing is lost.

## Quick start

```bash
pipx install kluris
kluris doctor                          # Check prerequisites
kluris create my-brain --type team   # Create a team brain
```

Then open any project and run `/kluris.learn` — the AI agent will analyze
your codebase and populate the brain with architecture, conventions, APIs,
and decisions.

### Example workflow

```bash
# 1. Create a brain for your team
kluris create acme-brain --type team

# 2. In your backend project, run the slash command:
#    /kluris.learn focus on architecture and API design

# 3. In your frontend project:
#    /kluris.learn focus on components and state management

# 4. Now any agent in any project can use the brain:
#    /kluris.think implement the new auth flow
#    (agent loads architecture decisions, API contracts, conventions from the brain)

# 5. After a session with useful decisions:
#    /kluris.remember

# 6. Validate and push
kluris dream                           # Regenerate indexes, check links
kluris push                            # Commit and push to git

# 7. Visualize the brain
kluris mri                             # Opens brain-mri.html
```

## What a brain looks like

```
acme-brain/
├── kluris.yml              # Brain config
├── brain.md                # Root index (auto-generated)
├── index.md                # Flat neuron list (auto-generated)
├── glossary.md             # Domain terms (hand-edited)
├── README.md               # Usage guide
├── architecture/
│   ├── map.md              # Lobe index (auto-generated)
│   ├── auth-keycloak.md    # <- neuron
│   └── data-flow.md        # <- neuron
├── decisions/
│   ├── map.md
│   └── use-raw-sql.md      # <- neuron (decision template)
├── services/
│   ├── map.md
│   └── btb-backend/
│       ├── map.md
│       ├── endpoints/
│       │   └── ...
│       └── data-model.md
└── ...
```

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

| Type | Lobes | Use case |
|------|-------|----------|
| `team` (default) | architecture, decisions, product, standards, services, infrastructure, cortex, wisdom | Shared team knowledge across projects |
| `personal` | projects, tasks, releases, notes | Individual developer brain |
| `product` | prd, features, ux, analytics, competitors, decisions | Product management |
| `research` | literature, experiments, findings, datasets, tools, questions | Research projects |
| `blank` | (empty) | Custom structure |

```bash
kluris create my-brain --type personal
kluris create product-brain --type product
```

## How it works

1. `kluris create` scaffolds a git repo with lobes, indexes, and a glossary
2. `kluris install` generates slash commands for 8 AI agents
3. Agents use `/kluris.learn` to scan projects and populate the brain
4. Team members use `/kluris.think <task>` to load brain context before working
5. `kluris dream` validates links, detects orphans, regenerates indexes
6. `kluris mri` generates an interactive HTML graph of the brain

## Slash commands (used inside AI agents)

| Command | What it does |
|---------|-------------|
| `/kluris <anything>` | **Main command.** Natural language. |
| `/kluris.think <task>` | Load brain context, work as team expert. |
| `/kluris.remember [topic]` | Extract knowledge from session. |
| `/kluris.learn [focus]` | Deep-scan project, populate brain. |
| `/kluris.recall <topic>` | Search the brain. |
| `/kluris.neuron <topic>` | Create a knowledge file. |
| `/kluris.lobe <name>` | Create a knowledge region. |
| `/kluris.push [msg]` | Commit and push to git. |
| `/kluris.dream [focus]` | AI-powered brain maintenance. |

## CLI commands

| Command | Flags | What it does |
|---------|-------|-------------|
| `kluris create <name>` | `--path`, `--type`, `--from-config`, `--json` | Create a new brain |
| `kluris clone <url> [path]` | `--json` | Clone an existing brain |
| `kluris list` | `--json` | List all registered brains |
| `kluris status` | `--brain`, `--json` | Brain tree and recent changes |
| `kluris recall <query>` | `--brain`, `--json` | Search across neurons |
| `kluris neuron <path>` | `--lobe`, `--template`, `--brain`, `--json` | Create a neuron |
| `kluris lobe <name>` | `--parent`, `--description`, `--brain`, `--json` | Create a lobe |
| `kluris dream` | `--brain`, `--json` | Regenerate maps, validate links |
| `kluris push` | `--message`, `--brain`, `--json` | Commit and push |
| `kluris mri` | `--brain`, `--output`, `--json` | Generate brain visualization |
| `kluris install` | `--json` | Install slash commands for agents |
| `kluris remove <name>` | `--json` | Unregister a brain |
| `kluris doctor` | `--json` | Check prerequisites |
| `kluris help [command]` | `--json` | Show help |

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

## Neuron templates

The `team` brain type includes templates for structured knowledge:

```bash
kluris neuron auth-migration.md --lobe decisions --template decision
```

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

## Brain vocabulary

| Term | Meaning |
|------|---------|
| **Brain** | Git repo of structured markdown |
| **Lobe** | Folder / knowledge region |
| **Neuron** | Single knowledge file |
| **Synapse** | Link between neurons (bidirectional) |
| **Map** | Auto-generated lobe index |
| **Index** | Flat list of all neurons |
| **MRI** | Interactive brain visualization |
| **Dream** | Brain maintenance — validate, repair |

## Supported agents

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

## License

MIT
