npm package: @sebbsssss/clude-brain
Description: Cognitive memory engine for AI agents — store, recall, and learn from experience
Author: Pixl64 LLP
Latest version: 0.1.0

# @clude/brain

Cognitive memory engine for AI agents. The core of [Clude](https://clude.io) — extracted as a standalone, provider-agnostic package.

## What is this?

`@clude/brain` is the memory engine that powers Clude. It handles:

- **Multi-type memory** — episodic, semantic, procedural, self_model
- **Scoring & ranking** — vector similarity, importance, decay, recency, Hebbian reinforcement
- **Entity extraction** — automatic entity and concept detection
- **Memory linking** — typed bonds between related memories
- **Provider-agnostic** — bring your own storage and embeddings

## Install

```bash
npm install @clude/brain
```

## Quick Start

```typescript
import { CludeEngine } from '@clude/brain';
import type { StorageProvider, EmbeddingProvider } from '@clude/brain';

// Bring your own providers
const engine = new CludeEngine({
  storage: myStorageProvider,
  embeddings: myEmbeddingProvider,
});

// Store a memory
await engine.store({
  content: "Auth bug was caused by expired JWT refresh token",
  type: "procedural",
  tags: ["auth", "debugging"],
  importance: 0.8,
});

// Recall relevant memories
const memories = await engine.recall({
  query: "authentication issues",
  limit: 5,
});
```

## Provider Interface

Implement these interfaces to connect any storage or embedding backend:

```typescript
interface StorageProvider {
  store(memory: Memory): Promise<string>;
  recall(options: RecallOptions): Promise<Memory[]>;
  get(id: string): Promise<Memory | null>;
  update(id: string, patch: Partial<Memory>): Promise<void>;
  delete(id: string): Promise<boolean>;
  stats(): Promise<MemoryStats>;
}

interface EmbeddingProvider {
  embed(text: string): Promise<number[]>;
  embedBatch(texts: string[]): Promise<(number[] | null)[]>;
  readonly dimensions: number;
}
```

## Available Providers

- **[@clude/cloud](https://www.npmjs.com/package/@clude/cloud)** — Supabase + Voyage AI (production)
- **[@clude/local](https://www.npmjs.com/package/@clude/local)** — SQLite + GTE-Small (offline, zero config)

## Memory Types

| Type | Purpose | Decay Rate |
|------|---------|------------|
| `episodic` | Events, conversations | Fast |
| `semantic` | Facts, knowledge | Slow |
| `procedural` | How-to, patterns | Very slow |
| `self_model` | Self-awareness | Very slow |

## Scoring

Memories are ranked by a weighted combination of:
- **Vector similarity** to the query
- **Importance** (0-1, with Hebbian reinforcement)
- **Recency** (time-decayed)
- **Decay factor** (type-dependent)
- **Access count** (frequently recalled memories rank higher)

## Part of the Clude ecosystem

- `@clude/brain` — This package. The memory engine.
- `@clude/cloud` — Supabase + Voyage providers.
- `@clude/local` — SQLite + local embeddings.
- `@clude/mcp` — MCP server for Claude Desktop / Cursor.
- `clude` — [Python SDK](https://pypi.org/project/clude/) (`pip install clude`)
- `clude-bot` — [Full bot](https://www.npmjs.com/package/clude-bot) with X integration, dream cycles, etc.

## License

MIT — [Pixl64 LLP](https://clude.io)