Metadata-Version: 2.4
Name: laeka-brain
Version: 0.3.1
Summary: MCP server — Laeka Brain cognitive layer for Claude Code
Project-URL: Homepage, https://laeka.ai
Project-URL: Documentation, https://laeka.ai/canonical
License: MIT
Keywords: brain,claude,laeka,mcp,omniq
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# laeka-brain

A cognitive layer for the AI you already use.

This MCP server connects your Claude Code environment to Laeka Brain — the Laeka protocol made available through six tools. It is a context provider. It does not call an LLM. It does not store your conversations. It returns context that Claude uses natively.

---

## What it is

Six tools, added to Claude Code via a single entry in `~/.claude/.mcp.json`:

- **`query`** — ask what Laeka Brain says about a concept or question
- **`reflect`** — share a situation; Brain holds the mirror and asks the question you haven't asked yourself
- **`consolidate`** — save a session insight to your personal mini-brain
- **`recall`** — semantic search across your personal mini-brain — find patterns and insights by natural language query
- **`list_brain_skills`** — browse the skill marketplace of an auxiliary brain (default: laeka-code)
- **`get_brain_skill`** — retrieve and apply a specific skill by name (e.g. `systematic-debugging`, `verification-before-completion`)

The four Laeka lenses — MONADE, SYMBIOTE, ARCHITECT, EMPATH — operate through all six tools. You will feel them before you name them.

---

## v0.2.2 — Honest 403 on subscription_required

v0.2.2: MCP tools now report `subscription_required` clearly on 403 instead of a generic "store unavailable" message. `list_brain_skills` and `get_brain_skill` both return `{"error": "subscription_required", "message": "...", "status": 403}` with an actionable upgrade link when the brain requires a paid addon.

## v0.2.1 — X-User-UUID header on brain skills calls

v0.2.1 passes the `X-User-UUID` header on `list_brain_skills` and `get_brain_skill` calls for tier-gated access compatibility. Users on paid tiers no longer receive 403 when accessing auxiliary brain skills.

## v0.2.0 — brain skills marketplace

v0.2.0 adds two new tools (`list_brain_skills`, `get_brain_skill`) that expose the Laeka Code skill marketplace — 28 rebranded engineering protocols available directly in Claude Code. Query, list, and apply skills from auxiliary brains like Laeka Code.

---

## How to install

**Requirements:** Python 3.12+, Claude Code.

```bash
pip install laeka-brain
```

Or without installing permanently:

```bash
uvx laeka-brain
```

---

## How to configure

Add this to `~/.claude/.mcp.json`:

```json
{
  "mcpServers": {
    "laeka-brain": {
      "command": "laeka-brain",
      "env": {
        "LAEKA_BRAIN_API_URL": "https://laeka.ai"
      }
    }
  }
}
```

If you installed via `uvx`, replace `"command"` with `"uvx laeka-brain"` or use the full `uvx` path.

**Environment variables:**

| Variable | Default | Description |
|---|---|---|
| `LAEKA_BRAIN_API_URL` | `https://laeka.ai` | Laeka Brain API base URL |
| `XDG_CONFIG_HOME` | `~/.config` | Override config dir location |

Your `user_uuid` is generated on first run and stored at `~/.config/laeka-brain/user_uuid`. It is the key to your personal mini-brain. Keep it — it cannot be recovered if lost.

---

## The 4 tools

### `query`

Ask what Laeka Brain says about something.

```
Use query with question="What does the ARCHITECT lens say about naming things in code?"
```

Returns the canonical Brain context framed around your question. Claude uses it as a cognitive lens — no LLM call happens inside this server.

### `reflect`

Share a situation. Brain holds the mirror.

```
Use reflect with situation="I've rewritten this module three times and I still don't like it."
```

Returns the canonical context plus a mirror directive. Claude applies the four lenses and asks the question that helps you see what you're not seeing. No advice. Just the mirror.

### `consolidate`

Persist a session insight to your mini-brain.

```
Use consolidate with text="Discovered that my naming friction is really a module boundary problem."
```

Stores the text as a `pattern_observation` in your personal memory cell. If your mini-brain doesn't exist yet, it is provisioned automatically.

### `recall`

Semantic search across your personal mini-brain.

```
Use recall with query="What did I learn about naming last week?"
```

Searches your stored patterns using vector similarity and returns the top matches ranked by relevance score. Each result shows the text snippet (up to 200 chars), sector, doc type, and creation date.

If the search endpoint is not yet available, returns your chunk count as a fallback so you always know where you stand.

---

## How to leave

If you want to remove Laeka Brain from your environment:

1. Remove the `laeka-brain` entry from `~/.claude/.mcp.json`.
2. Delete your local config: `rm -rf ~/.config/laeka-brain`
3. Optionally, destroy your mini-brain on the server:

```bash
curl -X POST https://laeka.ai/v1/brain/mini/offboard \
  -H "Content-Type: application/json" \
  -d "{\"user_uuid\": \"$(cat ~/.config/laeka-brain/user_uuid)\", \"confirm\": true}"
```

This destroys your private chunks permanently. Patterns that were anonymized and contributed to the collective remain as collective learning — they are not yours anymore, and they are not reversible.

No cron jobs. No daemons. No leftover files beyond `~/.config/laeka-brain/` (which you just deleted).

---

*Built with gratitude for Anthropic's foundational work. Laeka Brain is an extension that amplifies Claude Code — not a competitor, not a replacement.*
