npm package: @kybernesis/openclaw-kybernesis
Description: OpenClaw plugin for Kybernesis Brain - infinite context and memory with hybrid search, auto-tiering, and sleep agent capabilities
Author: Kybernesis AI
Latest version: 0.3.1

# Kybernesis for OpenClaw

> Infinite memory for your OpenClaw AI assistant

## Overview

**Kybernesis** gives your OpenClaw agent persistent, intelligent memory that works across every platform—Telegram, WhatsApp, Slack, Discord, and more.

### The Problem

OpenClaw's built-in memory relies on tool calls. The AI has to *decide* to access memory, and models don't do this consistently. Result: your AI forgets things it should know.

### The Solution

Kybernesis uses **auto-recall**—relevant memories are automatically injected into context *before* every turn. No tool calls needed. Your AI just knows.

**Key features:**

| Feature | What It Does |
|---------|--------------|
| **Auto-Recall** | Memories injected before every AI turn |
| **Auto-Capture** | Conversations saved automatically |
| **Hybrid Search** | 70% semantic + 30% metadata, sub-100ms |
| **Sleep Agent** | Background organization, tagging, and tiering |
| **Memory Tiering** | Hot → Warm → Archive based on usage |
| **Cross-Platform** | Same memory across all your chat apps |

---

## Quick Start

### 1. Install the Plugin

```bash
openclaw plugins install @kybernesis/openclaw-kybernesis
```

If you encounter module errors after installation, install dependencies:

```bash
cd ~/.openclaw/extensions/openclaw-kybernesis
npm install --omit=dev
```

### 2. Get Your API Key

1. Go to [kybernesis.ai](https://kybernesis.ai)
2. Create an account or sign in
3. Navigate to **Settings → API Keys**
4. Click **Generate New Key**
5. Copy your key (starts with `kb_...`)

### 3. Configure the Plugin

Set your API key via environment variable:

```bash
export KYBERNESIS_API_KEY=kb_your_key_here
```

Or configure in your OpenClaw config file (`~/.openclaw/openclaw.json`):

```json
{
  "plugins": {
    "entries": {
      "openclaw-kybernesis": {
        "enabled": true,
        "config": {
          "apiKey": "kb_your_key_here"
        }
      }
    }
  }
}
```

### 4. Verify Connection

Run the status command:

```
/kyber_status
```

You should see:

```
🧠 Kybernesis Status
━━━━━━━━━━━━━━━━━━━━━
Connection: ✅ OK
Endpoint: https://api.kybernesis.ai

📊 Memory Stats
Total: 0 memories
├─ 🔥 Hot: 0 (0%)
├─ 🌡️ Warm: 0 (0%)
└─ 🗄️ Archive: 0 (0%)

⚙️ Settings
Auto-recall: ✅ enabled
Auto-capture: ✅ enabled
```

You're ready to go!

---

## How It Works

### Auto-Recall (Before Every Turn)

When you send a message:

1. Your message is used as a search query
2. Kybernesis searches your entire memory (semantic + metadata)
3. Top matches are injected into the AI's context
4. The AI responds with full knowledge of relevant memories

**You don't have to ask** the AI to remember—it automatically has context.

### Auto-Capture (After Every Turn)

After each conversation turn:

1. Your message + AI response are combined
2. A title is generated from your message
3. The conversation is saved to your memory
4. Tags are automatically applied

**Your conversations become searchable knowledge**, automatically.

### Sleep Agent (Background Processing)

While you're away, the Sleep Agent:

- **Auto-tags** new memories based on content
- **Discovers relationships** between memories
- **Adjusts priority** based on access patterns
- **Summarizes** long content for faster retrieval
- **Tiers memories** (hot → warm → archive)

Your memory gets smarter without you doing anything.

---

## Commands

### `/remember` — Save Something Manually

Save specific information to memory:

```
/remember The project deadline is March 15th tags:project,deadlines
```

**Syntax:**
```
/remember <content> [tags:tag1,tag2,tag3]
```

**Examples:**
```
/remember My preferred coding style is functional TypeScript
/remember API key for Stripe is in 1Password tags:credentials,stripe
/remember Meeting notes: decided to use PostgreSQL for the database tags:meetings,architecture
```

### `/recall` — Search Manually

Search your memories:

```
/recall database architecture decisions limit:5
```

**Syntax:**
```
/recall <query> [limit:N]
```

**Examples:**
```
/recall project deadlines
/recall what did I decide about authentication limit:3
/recall TypeScript best practices
```

### `/kyber_status` — Check Status

View connection status, memory stats, and settings:

```
/kyber_status
```

Shows:
- Connection health
- Total memories by tier (hot/warm/archive)
- Source breakdown (chat/upload/connector)
- Current plugin settings

---

## Configuration Options

Configure via your OpenClaw config file (`~/.openclaw/openclaw.json`):

| Option | Default | Description |
|--------|---------|-------------|
| `apiKey` | — | Your API key (required, or set `KYBERNESIS_API_KEY` env var) |
| `mcpEndpoint` | `https://api.kybernesis.ai` | Server URL |
| `autoRecall` | `true` | Enable auto-recall |
| `autoCapture` | `true` | Enable auto-capture |
| `maxRecallResults` | `10` | Memories per turn (1-25) |
| `captureMinLength` | `50` | Min chars to trigger capture |
| `captureTags` | `openclaw` | Default tags for captures |
| `includeTierInfo` | `false` | Show tier labels in results |
| `debug` | `false` | Verbose logging |

### Example: Custom Configuration

```json
{
  "plugins": {
    "entries": {
      "openclaw-kybernesis": {
        "enabled": true,
        "config": {
          "apiKey": "kb_xxxxx",
          "mcpEndpoint": "https://api.kybernesis.ai",
          "autoRecall": true,
          "autoCapture": true,
          "maxRecallResults": 15,
          "captureMinLength": 50,
          "captureTags": "openclaw,personal",
          "includeTierInfo": true,
          "debug": false
        }
      }
    }
  }
}
```

---

## Tools (For Advanced Use)

The plugin exposes four tools your AI can use directly:

### `kybernesis_store`

Save content to memory:

```
Tool: kybernesis_store
Args: {
  "content": "The user prefers dark mode in all applications",
  "title": "User Preferences",
  "tags": ["preferences", "settings"]
}
```

### `kybernesis_search`

Search memories:

```
Tool: kybernesis_search
Args: {
  "query": "user preferences",
  "limit": 5
}
```

### `kybernesis_forget`

Delete a memory:

```
Tool: kybernesis_forget
Args: {
  "memoryId": "mem_abc123"
}
```

### `kybernesis_context`

Get memory statistics:

```
Tool: kybernesis_context
Args: {}
```

---

## Memory Tiering Explained

Memories automatically move between tiers based on usage:

### 🔥 Hot Tier
- Actively used memories
- Fast retrieval priority
- Recently accessed (within 3 days)
- High relationship density

### 🌡️ Warm Tier
- Occasionally accessed
- Moderate priority
- Accessed within 21 days
- Has manual tags

### 🗄️ Archive Tier
- Rarely accessed (30+ days)
- Still searchable
- Low priority score
- Minimal connections

**Tiering is automatic**—you don't need to manage it. The Sleep Agent handles promotion and demotion based on your actual usage patterns.

---

## Cross-Platform Sync

Your memory syncs across all OpenClaw platforms:

- **Telegram** → memories available in WhatsApp
- **WhatsApp** → memories available in Slack
- **Slack** → memories available in Discord
- **Discord** → memories available in Telegram

Start a conversation anywhere. Continue it anywhere else. Same context, always.

---

## Troubleshooting

### "Connection failed" error

1. Verify your API key is correct (starts with `kb_`)
2. Check your internet connection
3. Ensure `https://api.kybernesis.ai` is accessible
4. Try regenerating your API key

### "Cannot find module" error after installation

Install dependencies manually:

```bash
cd ~/.openclaw/extensions/openclaw-kybernesis
npm install --omit=dev
```

### Memories not being recalled

1. Run `/kyber_status` to verify auto-recall is enabled
2. Check that you have memories stored (total > 0)
3. Try `/recall` with a direct query to test search
4. Increase `maxRecallResults` in your config if needed

### Conversations not being captured

1. Verify auto-capture is enabled in `/kyber_status`
2. Check message length meets minimum (default: 50 chars)
3. Greetings and short commands are filtered out by design

### High latency

1. Check your network connection
2. Reduce `maxRecallResults` in your config for faster responses
3. Consider your distance from the API server

### Debug mode

Enable verbose logging in your OpenClaw config:

```json
{
  "plugins": {
    "entries": {
      "openclaw-kybernesis": {
        "config": {
          "debug": true
        }
      }
    }
  }
}
```

This will show detailed logs for every recall and capture operation.

---

## Privacy & Security

- **Your data stays yours**: Memories are stored in your Kybernesis workspace
- **API key authentication**: All requests require your personal API key
- **Encrypted in transit**: All communication uses HTTPS
- **No training on your data**: Your memories are never used to train models

---

## FAQ

**Q: Does this replace OpenClaw's built-in memory?**

It enhances it. OpenClaw's tool-based memory still works, but Kybernesis adds auto-recall so your AI doesn't have to "decide" to remember.

**Q: How many memories can I store?**

Unlimited. Kybernesis scales to thousands of memories with sub-100ms retrieval.

**Q: Will this slow down my AI?**

Retrieval takes <100ms. Most users don't notice any delay.

**Q: Can I use this with multiple OpenClaw instances?**

Yes. All instances using the same API key share the same memory.

**Q: How do I delete all my data?**

Contact support@kybernesis.ai or use the Kybernesis dashboard to delete your workspace.

---

## Support

- **Documentation**: [kybernesis.ai/docs](https://kybernesis.ai/docs)
- **Discord**: [Join our community](https://discord.gg/kybernesis)
- **Email**: support@kybernesis.ai
- **GitHub Issues**: [Report bugs](https://github.com/ianborders/kybernesis-brain/issues)

---

## Changelog

### v0.2.7 (Current)
- Fixed MCP API communication (SSE response parsing)
- Added proper Accept header for MCP protocol compliance

### v0.2.6
- Improved auto-recall relevance scoring
- Added tier info display option
- Fixed capture title generation for questions
- Better error handling for network issues

### v0.2.0
- Added Sleep Agent integration
- Memory tiering support
- Cross-platform sync

### v0.1.0
- Initial release
- Basic store/search/forget tools
- Auto-recall and auto-capture hooks

---

## License

MIT