Documentation

# Option 1: Docker Compose (recommended)
docker compose up -d

# Option 2: pip install
pip install knol

# Option 3: npm install
npm install @knol-dev/sdk

# Option 4: Build from source
cd knol-oss
cargo build --workspace --release

npm install -g knol-local

knol-local setup claude       # Claude Desktop (creates config if missing)
knol-local setup cursor       # Cursor (~/.cursor/mcp.json)
knol-local setup claude-code  # Claude Code CLI (claude mcp add)
knol-local setup codex        # Codex — shows HTTP API instructions
knol-local setup              # Auto-detect and configure all found clients

{ "mcpServers": { "knol-local": { "command": "knol-local" } } }

# Add a memory
knol-local add "Prefer strict TypeScript and functional patterns" --tag coding

# Search memories
knol-local search "TypeScript preferences" --limit 5

# List all memories
knol-local list --limit 20 --tag coding

# Summary statistics
knol-local stats

# Export / import
knol-local export --out backup.json
knol-local import backup.json

# Backup / restore the SQLite database
knol-local backup --out ~/backups/
knol-local restore ~/backups/memories-2026-05-09.db

# Start the HTTP REST API (useful for Codex)
knol-local serve --port 3001 --key my-secret

curl -X POST http://localhost:3000/v1/memory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers dark mode and concise responses",
    "user_id": "user-123",
    "metadata": {
      "source": "settings",
      "session_id": "sess-456"
    }
  }'

# Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "accepted",
  "message": "Memory queued for processing"
}

curl -X POST http://localhost:3000/v1/memory/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What does the user prefer?",
    "user_id": "user-123",
    "limit": 5,
    "memory_types": ["semantic", "episodic"]
  }'

# Response — hybrid retrieval fuses vector + BM25 + graph
{
  "results": [
    {
      "id": "550e8400-...",
      "content": "User prefers dark mode and concise responses",
      "memory_type": "semantic",
      "score": 0.94,
      "created_at": "2026-02-15T10:30:00Z"
    }
  ],
  "query_intent": "preference",
  "retrieval_strategy": "vector_primary"
}

import { KnolClient } from '@knol-dev/sdk';

const knol = new KnolClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'your-api-key',
});

// Store
await knol.add({
  content: 'User prefers TypeScript and functional patterns',
  userId: 'user-123',
});

// Search
const results = await knol.search({
  query: 'programming preferences',
  userId: 'user-123',
});

// Knowledge graph
const entities = await knol.listEntities({ userId: 'user-123' });

{
  "error": "Missing required field: content"
}

{
  "error": "Rate limit exceeded. Maximum 10 requests per minute on Free plan"
}

curl -X POST http://localhost:3000/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["memory.created", "conflict.detected"],
    "active": true
  }'

# Response
{
  "id": "webhook-550e8400-e29b",
  "url": "https://your-app.com/webhook",
  "events": ["memory.created", "conflict.detected"],
  "active": true,
  "created_at": "2026-02-15T10:30:00Z"
}

curl -X POST http://localhost:3000/v1/memory/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {
        "content": "User prefers dark mode",
        "user_id": "user-123",
        "metadata": {"source": "settings"}
      },
      {
        "content": "User knows TypeScript and Rust",
        "user_id": "user-123",
        "metadata": {"source": "profile"}
      }
    ]
  }'

# Response
{
  "inserted": 2,
  "ids": ["550e8400-e29b-41d4-...", "550e8400-e29c-41d4-..."],
  "status": "accepted"
}