### Install MuninnDB SDKs

Source: https://muninndb.com/docs/sdks

Commands to install the MuninnDB client libraries for Go and Python.

```bash
go get github.com/scrypster/muninndb/sdk/go/muninn
```

```bash
pip install muninndb
# or: pip install muninn-python
# With LangChain: pip install muninndb[langchain]
```

--------------------------------

### Initialize MuninnDB services

Source: https://muninndb.com/docs/quickstart

Command to initialize the environment, connect AI tools, and start the MuninnDB services.

```bash
muninn init

# Guided wizard — connects Claude Desktop, Cursor, VS Code, Windsurf
# and starts all services automatically.
#
# muninn started (pid 12345)
#   MBP  :8474   binary protocol
#   REST :8475   JSON API
#   gRPC :8477   gRPC API
#   MCP  :8750   AI tool integration
#   UI   :8476   http://localhost:8476
```

--------------------------------

### Install MuninnDB on macOS/Linux

Source: https://muninndb.com/docs/installation

Use this script for a quick installation on macOS or Linux. It automatically detects your platform and places the binary in /usr/local/bin/muninn.

```bash
curl -fsSL https://muninndb.com/install.sh | sh
```

--------------------------------

### Install MuninnDB binary

Source: https://muninndb.com/docs/quickstart

Commands to download and install the MuninnDB binary on macOS, Linux, or Windows.

```bash
# macOS / Linux
curl -fsSL https://muninndb.com/install.sh | sh

# macOS (Homebrew)
brew install scrypster/tap/muninn

# Windows (PowerShell)
irm https://muninndb.com/install.ps1 | iex
```

--------------------------------

### Start MuninnDB Node

Source: https://muninndb.com/docs/clustering

Start a MuninnDB node using the specified configuration file. Observe the log output for connection status and cluster role assignment.

```bash
muninn start --config /etc/muninn/muninn.yaml

# [INFO] cluster mode enabled, node_id=muninn-01
# [INFO] connecting to seed 10.0.1.11:8474... connected
# [INFO] connecting to seed 10.0.1.12:8474... connected
# [INFO] participating in election, epoch=1
# [INFO] elected as cortex (received 2/3 votes)
# [INFO] MuninnDB ready (role=cortex, cluster_size=3)
```

--------------------------------

### MuninnDB Server Start Flags

Source: https://muninndb.com/docs/configuration

Use these flags with the `muninn start` command to configure server options like data directory, listen addresses, and log level. Defaults are provided for most options.

```bash
--data <dir>        Data directory            default: ~/.muninn/data
--mbp-addr <addr>  MBP TCP listen address   default: :8474
--rest-addr <addr> REST HTTP listen address  default: :8475
--grpc-addr <addr> gRPC listen address       default: :8477
--mcp-addr <addr>  MCP listen address        default: :8750
--mcp-token <tok>  Bearer token for MCP auth (empty = no auth)
--log-level <lvl>  Log level: debug, info, warn, error  default: info
--dev              Serve web assets from ./web (hot-reload)
```

--------------------------------

### MuninnDB Initial Setup and Service Management

Source: https://muninndb.com/docs/installation

Commands for initializing MuninnDB, starting/stopping services, checking status, and accessing the interactive memory explorer. Also lists default ports for various services.

```bash
muninn init     # first-time guided setup
muninn start    # start all services in background
muninn status   # check which services are running
muninn stop     # stop the running server
muninn shell    # interactive memory explorer

# Ports:
# MBP  :8474   binary protocol
# REST :8475   JSON API
# gRPC :8477   gRPC API
# MCP  :8750   AI tool integration (http://localhost:8750/mcp)
# UI   :8476   web dashboard (http://localhost:8476)
```

--------------------------------

### Install MuninnDB on Windows (PowerShell)

Source: https://muninndb.com/docs/installation

Run this PowerShell command on Windows to download, extract, and add MuninnDB to your PATH. Ensure Visual C++ Redistributable is installed if you encounter ORT/DLL errors.

```powershell
irm https://muninndb.com/install.ps1 | iex
```

--------------------------------

### Structured JSON Log Example

Source: https://muninndb.com/docs/observability

This is an example of the structured JSON log output generated by MuninnDB. Pipe this output to any log aggregator for analysis.

```json
{"time":"2026-02-21T10:00:00Z","level":"INFO","msg":"activate","vault":"default","duration_ms":12,"results":5,"context_len":24}
```

--------------------------------

### Install and Update MuninnDB with Homebrew

Source: https://muninndb.com/docs/installation

macOS users can install MuninnDB using Homebrew. The command also shows how to upgrade to the latest version later.

```bash
brew install scrypster/tap/muninn

# To update later:
brew upgrade muninn
```

--------------------------------

### Store memory via SDK

Source: https://muninndb.com/docs/quickstart

Examples for writing a new memory entry to a vault using the Go and Python SDKs.

```go
client := muninn.NewClient("http://localhost:8475", "your-token")

engID, err := client.Write(ctx, "default",
    "user prefers dark mode",
    "Always render UI in dark theme for this user",
    []string{"preference", "ui"})
fmt.Printf("Stored: %s\n", engID)
```

```python
import asyncio
from muninn import MuninnClient

async def main():
    async with MuninnClient("http://localhost:8475", token="your-token") as client:
        eng_id = await client.write(
            vault="default",
            concept="user prefers dark mode",
            content="Always render UI in dark theme for this user",
            tags=["preference", "ui"],
        )
        print(f"Stored: {eng_id}")

asyncio.run(main())
```

--------------------------------

### Configure Embedder with Environment Variables

Source: https://muninndb.com/docs/installation

Enable semantic similarity by setting the MUNINN_OLLAMA_URL or MUNINN_OPENAI_KEY environment variables before starting MuninnDB.

```bash
MUNINN_OLLAMA_URL=ollama://localhost:11434/nomic-embed-text muninn start
MUNINN_OPENAI_KEY=sk-...  muninn start
```

--------------------------------

### Generate Python gRPC Client

Source: https://muninndb.com/docs/api/grpc

Commands to install gRPC tools and generate Python client code from the service definition.

```bash
pip install grpcio grpcio-tools

python -m grpc_tools.protoc \
  -I proto/muninn/v1 \
  --python_out=. \
  --grpc_python_out=. \
  proto/muninn/v1/service.proto
```

--------------------------------

### OpenAI Configuration for Enrichment

Source: https://muninndb.com/docs/plugins

Example configuration for using OpenAI's models with the Enrich plugin. Specify the provider, model, and API key.

```yaml
provider: openai
model: gpt-4o-mini
api_key: ${OPENAI_API_KEY}
```

--------------------------------

### Example 'Why' Field Output

Source: https://muninndb.com/docs/activate

Illustrates the format of the 'Why' field returned by the ACTIVATE query, detailing the breakdown of the engram's score components and overall relevance/confidence.

```text
BM25(0.78) + hebbian_boost(0.16) + assoc_depth1(0.06)
relevance=0.91, confidence=0.95, access_count=14
```

--------------------------------

### Activate relevant memories

Source: https://muninndb.com/docs/quickstart

Examples for retrieving cognitively relevant engrams based on context using the Go and Python SDKs.

```go
results, err := client.Activate(ctx, "default", []string{"what does the user want?"}, 5)

for _, r := range results.Engrams {
    fmt.Printf("%.2f — %s\n", r.Score, r.Concept)
    fmt.Printf("  Why: %s\n", r.Why)
}

// Output:
// 0.94 — user prefers dark mode
//   Why: BM25 match (0.78) + Hebbian boost (0.16)
```

```python
results = await client.activate(
    vault="default", context=["what does the user want?"])

for r in results.engrams:
    print(f"{r.score:.2f} — {r.concept}")
    print(f"  Why: {r.why}")

# Output:
# 0.94 — user prefers dark mode
#   Why: BM25 match (0.78) + Hebbian boost (0.16)
```

--------------------------------

### Enable Embed Plugin with Environment Variables

Source: https://muninndb.com/docs/plugins

Configure the Embed plugin by setting environment variables before starting MuninnDB. Choose your embedding provider (Ollama, OpenAI, Voyage AI) and set the corresponding URL or API key.

```bash
# Ollama (local, no key required)
MUNINN_OLLAMA_URL=ollama://localhost:11434/nomic-embed-text muninn start

# OpenAI
MUNINN_OPENAI_KEY=sk-... muninn start

# Voyage AI
MUNINN_VOYAGE_KEY=pa-... muninn start
```

--------------------------------

### Generate Cluster Secret

Source: https://muninndb.com/docs/clustering

Use openssl to generate a strong, random secret for cluster authentication. Store this secret securely, for example, in an environment variable.

```bash
openssl rand -hex 32
# export MUNINN_CLUSTER_SECRET=$(openssl rand -hex 32)
```

--------------------------------

### Basic ACTIVATE Query in Go

Source: https://muninndb.com/docs/activate

Demonstrates how to initialize a MuninnDB client and perform an ACTIVATE query to retrieve engrams. Handles potential errors and iterates through results to print scores and explanations.

```go
client := muninn.NewClient("http://localhost:8475", "your-token")

results, err := client.Activate(ctx, "default",
    []string{"what are the user's preferences?"}, 10)
if err != nil {
    log.Fatal(err)
}

for _, r := range results.Engrams {
    fmt.Printf("Score: %.3f  Concept: %s\n", r.Score, r.Concept)
    fmt.Printf("Why: %s\n", r.Why)
}
```

--------------------------------

### muninn_guide

Source: https://muninndb.com/docs/api/mcp

Retrieves vault-aware usage instructions for the AI, including guidance on when to remember, recall, and suggested behavior modes.

```APIDOC
## POST /mcp/muninn_guide

### Description
Get vault-aware usage instructions for the AI. Call on first connect; returns when to remember, when to recall, behavior mode, and quick tips.

### Method
POST

### Endpoint
`http://localhost:8750/mcp`

### Parameters
#### Request Body
- **vault** (string) - Optional - Vault name (default: "default")

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "muninn_guide",
  "params": {
    "vault": "my_vault"
  },
  "id": 1
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains usage instructions and AI guidance.
- **error** (object) - Contains error details if the operation failed.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "guidance": "Remember important facts, recall relevant memories for context, operate in analytical mode."
  },
  "id": 1
}
```
```

--------------------------------

### Basic ACTIVATE Query in Python

Source: https://muninndb.com/docs/activate

Shows how to use the MuninnDB Python client to perform an ACTIVATE query. It connects to the client, executes the query, and then prints the score and 'Why' explanation for each returned engram.

```python
async with MuninnClient("http://localhost:8475", token="your-token") as client:
    results = await client.activate(
        vault="default",
        context=["what are the user's preferences?"])

    for r in results.engrams:
        print(f"Score: {r.score:.3f}  Concept: {r.concept}")
        print(f"Why: {r.why}")
```

--------------------------------

### muninn_traverse

Source: https://muninndb.com/docs/api/mcp

Performs a graph traversal starting from a specified memory, following association links to discover connected memories.

```APIDOC
## POST /mcp/muninn_traverse

### Description
Graph traversal from a starting memory. Follows association links hop-by-hop to find connected memories you may not know to ask for directly.

### Method
POST

### Endpoint
`http://localhost:8750/mcp`

### Parameters
#### Request Body
- **start_id** (string) - Required - Starting engram ULID
- **vault** (string) - Optional - Vault name (default: "default")
- **max_hops** (int) - Optional - Max graph depth (default 2, max 5)
- **max_nodes** (int) - Optional - Max total results (default 20, max 100)
- **rel_types** ([]string) - Optional - Filter by relation types

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "muninn_traverse",
  "params": {
    "start_id": "ulid-start",
    "vault": "my_vault",
    "max_hops": 3,
    "max_nodes": 50,
    "rel_types": ["depends_on", "related_to"]
  },
  "id": 1
}
```

### Response
#### Success Response (200)
- **result** (array) - An array of connected memory engrams found through traversal.
- **error** (object) - Contains error details if the operation failed.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": [
    { "id": "ulid-connected1", "content": "Content of connected memory 1" },
    { "id": "ulid-connected2", "content": "Content of connected memory 2" },
    ...
  ],
  "id": 1
}
```
```

--------------------------------

### Generate a Client (Go)

Source: https://muninndb.com/docs/api/grpc

Instructions for generating a Go gRPC client for MuninnDB.

```APIDOC
## Generate a Client (Go)

Grab the proto file from the repo and generate a client for your language:
bash — Go (already generated, available in repo)
```
protoc --go_out=. --go-grpc_out=. \
  proto/muninn/v1/service.proto
```
```

--------------------------------

### Readiness Probe

Source: https://muninndb.com/docs/api/rest

Use the `/ready` endpoint as a readiness probe. It returns 200 when all workers are initialized and requires no authentication.

```http
GET /ready
```

--------------------------------

### Generate a Client (Python)

Source: https://muninndb.com/docs/api/grpc

Instructions for generating a Python gRPC client for MuninnDB using `grpcio-tools`.

```APIDOC
## Generate a Client (Python)

Grab the proto file from the repo and generate a client for your language:
bash — Python client
```
pip install grpcio grpcio-tools

python -m grpc_tools.protoc \
  -I proto/muninn/v1 \
  --python_out=. \
  --grpc_python_out=. \
  proto/muninn/v1/service.proto
```
```

--------------------------------

### GET /api/admin/vaults/{vault_name}/job-status

Source: https://muninndb.com/docs/vault-management

Retrieves the status of a background job, such as a vault clone operation. This allows monitoring the progress and checking for errors.

```APIDOC
## GET /api/admin/vaults/{vault_name}/job-status

### Description
Retrieves the status of a background job, such as a vault clone operation. This allows monitoring the progress and checking for errors.

### Method
GET

### Endpoint
/api/admin/vaults/{vault_name}/job-status

### Parameters
#### Query Parameters
- **job_id** (string) - Required - The ID of the job to check.

#### Path Parameters
- **vault_name** (string) - Required - The name of the vault associated with the job.

### Response
#### Success Response (200 OK)
- **status** (string) - The current status of the job (e.g., "copying", "indexing", "done", "error").
- **phase** (string) - The current phase of the job (e.g., "indexing").
- **copy_total** (integer) - The total number of engrams to copy.
- **copy_current** (integer) - The number of engrams currently copied.
- **index_total** (integer) - The total number of engrams to index.
- **index_current** (integer) - The number of engrams currently indexed.
- **pct** (number) - The overall progress percentage.
- **error** (string) - An error message if the job failed, otherwise empty.

#### Response Example
```json
{
  "status":        "indexing",
  "phase":         "indexing",
  "copy_total":    5000,
  "copy_current":  5000,
  "index_total":   5000,
  "index_current": 2100,
  "pct":           62.0,
  "error":         ""
}
```

### Error Handling
- **404 Not Found**: Vault or job ID not found.
- **500 Internal Server Error**: An unexpected error occurred on the server.
```

--------------------------------

### Create Link Between Engrams

Source: https://muninndb.com/docs/api/rest

Create an explicit weighted association between two engrams using the `/link` endpoint. The `rel_type` parameter defines the relationship, with custom types starting at 0x8000.

```json
{
  "vault":     "default",
  "source_id": "01JN...",
  "target_id": "01JN...",
  "rel_type":  5,
  "weight":    0.8
}
```

--------------------------------

### Enable Enrich Plugin with Environment Variables

Source: https://muninndb.com/docs/plugins

Configure the Enrich plugin by setting environment variables. Specify the enrichment URL for providers like Anthropic, OpenAI, or Ollama, along with any necessary API keys.

```bash
# Anthropic (recommended)
MUNINN_ENRICH_URL=anthropic://claude-haiku-4-5-20251001
MUNINN_ANTHROPIC_KEY=sk-ant-... muninn start

# OpenAI
MUNINN_ENRICH_URL=openai://gpt-4o-mini
MUNINN_OPENAI_API_KEY=sk-... muninn start

# Ollama (local, no key)
MUNINN_ENRICH_URL=ollama://localhost:11434/llama3.2 muninn start

# Enrichment runs asynchronously and does not block memory writes.
```

--------------------------------

### Configure MuninnDB with CLI Flags

Source: https://muninndb.com/docs/installation

Configure MuninnDB settings using command-line flags. Key flags include specifying the data directory, MCP token and address, and log level.

```bash
muninn start --data /path/to/data    # Custom data directory (default: ~/.muninn/data)
muninn start --mcp-token my-token    # MCP bearer token
muninn start --mcp-addr :9000        # Custom MCP port
muninn start --log-level debug       # Log verbosity: debug, info, warn, error
```

--------------------------------

### Create a Semantic Trigger in Python

Source: https://muninndb.com/docs/triggers

Set up a callback function to handle trigger events for a specified context and relevance threshold. Remember to cancel the subscription when it's no longer needed.

```Python
def on_trigger(event):
    print(f"Alert! Relevant memory: {event.engram.concept}")

sub = mem.subscribe(
    context="production deployment failure",
    threshold=0.8,   # Fire when relevance >= 0.8
    callback=on_trigger,
)

# Cancel when done
sub.cancel()
```

--------------------------------

### Generate Go gRPC Client

Source: https://muninndb.com/docs/api/grpc

Command to generate Go client code from the service definition.

```bash
protoc --go_out=. --go-grpc_out=. \
  proto/muninn/v1/service.proto
```

--------------------------------

### Use Client API for Advanced Operations

Source: https://muninndb.com/docs/sdks

Low-level interface for vault management, batch operations, and custom client configuration.

```go
// NewClient(baseURL, token string) — REST on port 8475
client := muninn.NewClient("http://localhost:8475", "api-key")

// Custom options (timeout, retries, backoff)
client = muninn.NewClientWithOptions(
    "http://localhost:8475", "api-key",
    10*time.Second, 5, 500*time.Millisecond)

// Health check
client.Health(ctx)
```

```python
from muninn import MuninnClient

# MuninnClient(base_url, *, token=None)
async with MuninnClient("http://localhost:8475", token="api-key") as client:
    # Health check
    await client.health()

    # Stats
    stats = await client.stat(vault="default")
```

--------------------------------

### Configure LLM Enrichment with Environment Variables

Source: https://muninndb.com/docs/installation

Enable optional LLM enrichment for auto-summaries and entity extraction by setting MUNINN_ENRICH_URL and MUNINN_ANTHROPIC_KEY environment variables.

```bash
MUNINN_ENRICH_URL=anthropic://claude-haiku-4-5-20251001 \
MUNINN_ANTHROPIC_KEY=sk-ant-... muninn start
```

--------------------------------

### Configure MuninnDB Clustering via YAML

Source: https://muninndb.com/docs/clustering

Use the muninn.yaml file to define cluster settings, including node identification, network binding, and peer discovery.

```yaml
cluster:
  enabled: true
  node_id: "muninn-01"        # unique, stable across restarts
  bind_addr: "10.0.1.10:8474" # replication listen address
  seeds:                       # initial peers to contact at startup
    - "10.0.1.11:8474"
    - "10.0.1.12:8474"
  cluster_secret: "your-shared-secret"  # same on all nodes
  lease_ttl: 10               # seconds before a dead leader is evicted
  heartbeat_ms: 1000          # heartbeat interval
```

--------------------------------

### Create a Semantic Trigger in Go

Source: https://muninndb.com/docs/triggers

Subscribe to a context string to receive notifications when engrams cross a relevance threshold. Ensure to cancel the subscription when done to prevent resource leaks.

```Go
sub, err := mem.Subscribe(ctx, &muninn.TriggerRequest{
    Context:   "production deployment failure",
    Threshold: 0.8,             // Fire when relevance >= 0.8
    Callback: func(e *muninn.TriggerEvent) {
        fmt.Printf("Alert! Relevant memory: %s\n", e.Engram.Concept)
    },
})

defer sub.Cancel()
```

--------------------------------

### Configure MuninnDB MCP Server in Claude Desktop

Source: https://muninndb.com/docs/protocols

Add the MuninnDB MCP server configuration to your Claude Desktop settings. This allows AI agents to connect to MuninnDB for memory and context operations.

```json
{
  "mcpServers": {
    "muninndb": {
      "type": "http",
      "url": "http://localhost:8750/mcp",
      "headers": {
        "Authorization": "Bearer mk_xK9m..."
      }
    }
  }
}
```

--------------------------------

### Configure MuninnDB Clustering via Environment Variables

Source: https://muninndb.com/docs/clustering

Environment variables can be used to override settings defined in the muninn.yaml configuration file.

```bash
# Environment variables override muninn.yaml values
MUNINN_CLUSTER_ENABLED=true
MUNINN_CLUSTER_NODE_ID=muninn-01
MUNINN_CLUSTER_BIND_ADDR=10.0.1.10:8474
MUNINN_CLUSTER_SEEDS=10.0.1.11:8474,10.0.1.12:8474
MUNINN_CLUSTER_SECRET=your-shared-secret
```

--------------------------------

### Authentication Header

Source: https://muninndb.com/docs/api/rest

Use this header for authenticated API requests. Tokens are generated via `muninn init` or the admin API.

```http
Authorization: Bearer mk_xK9m...
```

--------------------------------

### Monitor Cluster Health (CLI)

Source: https://muninndb.com/docs/clustering

Use CLI commands to monitor the overall cluster state, including the current Cortex, election epoch, and per-node health metrics like replication lag.

```bash
muninn cluster info    # cluster state, current Cortex, epoch
muninn cluster status  # per-node health and replication lag
```

--------------------------------

### Check engram statistics

Source: https://muninndb.com/docs/troubleshooting

Retrieve engram counts by state to debug why ACTIVATE returns zero results.

```bash
curl http://localhost:8475/api/stats   # Check engram counts by state
```

--------------------------------

### MuninnDB LLM Enrichment Environment Variables

Source: https://muninndb.com/docs/configuration

Enable automatic extraction of summaries, entities, and relationships using LLM enrichment. The URL scheme selects the provider, and API keys are set via environment variables.

```bash
# URL scheme selects the provider:
MUNINN_ENRICH_URL=ollama://localhost:11434/llama3.2           # local, no key
MUNINN_ENRICH_URL=openai://gpt-4o-mini
MUNINN_ENRICH_API_KEY=sk-...
MUNINN_ENRICH_URL=anthropic://claude-haiku-4-5-20251001
MUNINN_ANTHROPIC_KEY=sk-ant-...  # alias for MUNINN_ENRICH_API_KEY
```

--------------------------------

### Verify service status

Source: https://muninndb.com/docs/troubleshooting

Check which MuninnDB services are currently running.

```bash
muninn status   # Check which services are running
```

--------------------------------

### Manage Cluster Nodes via CLI

Source: https://muninndb.com/docs/clustering

Interactive commands for adding new nodes to the cluster or removing existing ones.

```bash
# Get instructions for joining a new node
muninn cluster add-node

# Get instructions for cleanly removing a node
muninn cluster remove-node --node muninn-03
```

--------------------------------

### Health Probe

Source: https://muninndb.com/docs/api/rest

Use the `/health` endpoint as a liveness probe. It returns 200 when the server is up and requires no authentication.

```http
GET /health
```

--------------------------------

### Enable Decay Worker Configuration

Source: https://muninndb.com/docs/cognitive-workers

Configuration setting to enable the opt-in Decay Worker for backward compatibility.

```properties
workers.decay.enabled = true
```

--------------------------------

### Trigger Manual Cluster Failover (REST API)

Source: https://muninndb.com/docs/clustering

Initiate a graceful failover of the cluster Cortex node using the REST API. Ensure proper authorization is provided.

```bash
curl -X POST http://localhost:8475/v1/replication/promote \
  -H "Authorization: Bearer mn_admin_..."
```

--------------------------------

### RPC Methods

Source: https://muninndb.com/docs/api/grpc

Detailed descriptions of each RPC method available in the MuninnDB gRPC service.

```APIDOC
## RPC Methods

`Hello`
Unary
Auth handshake. Validates the connection and returns server version info.

`Write`
Unary
Store a new engram. Accepts vault, concept, content, tags, and confidence. Returns the engram ULID.

`Read`
Unary
Fetch a single engram by ULID. Returns the full record including temporal priority data (access count, last access), Hebbian score, and associations.

`Forget`
Unary
Soft-delete an engram. Archives it — excluded from activation but restorable for 7 days.

`Stat`
Unary
Vault statistics: engram count, storage bytes, coherence scores per vault.

`Link`
Unary
Create a typed association between two engrams. Supports all 15 built-in relation types (supports, contradicts, depends_on, is_part_of, causes, etc.) plus user-defined types.

`Activate`
Server-streaming
Cognitive retrieval. Results are streamed back as they are scored — useful for large result sets or early termination. Runs the full 6-phase pipeline.

`Subscribe`
Bidirectional streaming
Real-time push stream. Send SubscribeRequest frames to update your watch context; receive ActivationPush frames when relevant memories are activated above the threshold.
```

--------------------------------

### Activate Engrams with Context

Source: https://muninndb.com/docs/engrams

Use the `activate` method to find the most relevant engrams for a given context. Ensure the 'default' vault is accessible.

```javascript
results = await client.activate(
    vault="default",
    context=["what database do we use?"])

```

--------------------------------

### Lifecycle & State Management

Source: https://muninndb.com/docs/api/mcp

Endpoints for managing the lifecycle and state of memories.

```APIDOC
## POST /muninn_evolve

### Description
Update a memory with new content while preserving its history. The old version is archived and linked. Tracks why the memory changed.

### Method
POST

### Endpoint
/muninn_evolve

### Parameters
#### Request Body
- **id** (string) - Required - Engram ULID
- **new_content** (string) - Required - The updated information
- **reason** (string) - Required - Why this memory changed
- **vault** (string) - Optional - Vault name (default: "default")

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "Memory evolved successfully."
}
```
```

```APIDOC
## POST /muninn_state

### Description
Transition a memory's lifecycle state. Useful for tracking work in progress, decisions, or task status.

### Method
POST

### Endpoint
/muninn_state

### Parameters
#### Request Body
- **id** (string) - Required - Engram ULID
- **state** (string) - Required - planning · active · paused · blocked · completed · cancelled · archived
- **vault** (string) - Optional - Vault name (default: "default")
- **reason** (string) - Optional - Optional note on the transition

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "Memory state updated successfully."
}
```
```

```APIDOC
## POST /muninn_decide

### Description
Record a decision with its rationale and supporting evidence. Creates a structured decision engram automatically linked to referenced evidence.

### Method
POST

### Endpoint
/muninn_decide

### Parameters
#### Request Body
- **decision** (string) - Required - The decision made
- **rationale** (string) - Required - Why this decision was made
- **vault** (string) - Optional - Vault name (default: "default")
- **alternatives** ([]string) - Optional - Options that were considered but not chosen
- **evidence_ids** ([]string) - Optional - ULIDs of engrams supporting this decision

### Response
#### Success Response (200)
- **message** (string) - Confirmation message
- **decision_id** (string) - The ULID of the created decision engram

#### Response Example
```json
{
  "message": "Decision recorded successfully.",
  "decision_id": "ulid_of_the_decision"
}
```
```

```APIDOC
## POST /muninn_restore

### Description
Recover a soft-deleted memory within the 7-day restoration window.

### Method
POST

### Endpoint
/muninn_restore

### Parameters
#### Request Body
- **id** (string) - Required - Engram ULID
- **vault** (string) - Optional - Vault name (default: "default")

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "Memory restored successfully."
}
```
```

--------------------------------

### Check system health

Source: https://muninndb.com/docs/troubleshooting

Query the health endpoint to monitor system status and memory usage.

```bash
curl http://localhost:8475/api/health   # Check system health
```

--------------------------------

### Activate Engrams

Source: https://muninndb.com/docs/api/rest

Use the `/activate` endpoint for primary retrieval. This endpoint runs a full cognitive pipeline including BM25 scoring, temporal priority scoring, Hebbian boosting, and graph traversal.

```json
{
  "vault":       "default",
  "context":     ["what does the user prefer?"],
  "max_results": 10,
  "threshold":   0.5,
  "max_hops":    2
}
```

--------------------------------

### Client API Operations

Source: https://muninndb.com/docs/sdks

Low-level interface for direct database operations, vault management, and system monitoring.

```APIDOC
## Client API Operations

### Description
The Client API provides granular control over MuninnDB, including health checks, statistics, and custom configuration for timeouts and retries.

### Methods
- **Health**: Checks the status of the MuninnDB instance.
- **Stat**: Retrieves statistics for a specific vault.

### Parameters
- **vault** (string) - Required - The target vault name for statistics.
- **baseURL** (string) - Required - The server address (default port 8475).
- **token** (string) - Required - API authentication key.
```

--------------------------------

### Use Memory API for Common Operations

Source: https://muninndb.com/docs/sdks

High-level interface for storing, retrieving, and subscribing to engrams with automatic connection pooling.

```go
client := muninn.NewClient("http://localhost:8475", "api-key")

// Store
engID, _ := client.Write(ctx, "default", "concept", "content", []string{"tag"})

// Activate (cognitive retrieval)
results, _ := client.Activate(ctx, "default", []string{"user question context"}, 10)

// Get by ID
engram, _ := client.Read(ctx, "default", id)

// Subscribe to push events
stream, _ := client.Subscribe(ctx, "default")
for push := range stream.C() { ... }
```

```python
from muninn import MuninnClient

async with MuninnClient("http://localhost:8475", token="api-key") as client:
    # Store
    eng_id = await client.write(
        vault="default", concept="...", content="...", tags=[])

    # Activate (cognitive retrieval)
    results = await client.activate(
        vault="default", context=["user question context"])

    # Get by ID
    engram = await client.read(vault="default", engram_id=eng_id)

    # Subscribe to push events
    async for push in client.subscribe(vault="default"):
        print(push.engram_id)
```

--------------------------------

### MuninnDB Other Environment Variables

Source: https://muninndb.com/docs/configuration

Configure other MuninnDB settings using environment variables, such as overriding the data directory or specifying allowed CORS origins.

```bash
MUNINNDB_DATA=<dir>       Override default data directory
MUNINN_CORS_ORIGINS=<o>  Comma-separated allowed CORS origins
```

--------------------------------

### Store Engrams

Source: https://muninndb.com/docs/engrams

Create and store a new engram in a specified vault using the MuninnDB client.

```go
client := muninn.NewClient("http://localhost:8475", "your-token")

engID, err := client.Write(ctx, "default",
    "database is PostgreSQL-compatible",
    "The backend uses PostgreSQL 15 with pgvector extension",
    []string{"infrastructure", "database"})
```

```python
async with MuninnClient("http://localhost:8475", token="your-token") as client:
    eng_id = await client.write(
        vault="default",
        concept="database is PostgreSQL-compatible",
        content="The backend uses PostgreSQL 15 with pgvector extension",
        tags=["infrastructure", "database"],
    )
```

--------------------------------

### MuninnDB Embedder Environment Variables

Source: https://muninndb.com/docs/configuration

Configure embedders for semantic similarity search using environment variables. Only one embedder can be enabled at a time, with priority given to the first one set.

```bash
MUNINN_OLLAMA_URL=ollama://localhost:11434/nomic-embed-text  # local, no key
MUNINN_OPENAI_KEY=sk-...                                     # text-embedding-3-small
MUNINN_VOYAGE_KEY=pa-...                                     # voyage-3
```

--------------------------------

### Query Cluster Status and Health via API

Source: https://muninndb.com/docs/clustering

Use these endpoints to monitor node status and cluster health for load balancing or monitoring systems.

```bash
curl http://localhost:8475/v1/cluster/nodes \
  -H "Authorization: Bearer mn_admin_..."
```

```bash
curl http://localhost:8475/v1/cluster/health
```

--------------------------------

### Activate Cognitive Retrieval using REST API

Source: https://muninndb.com/docs/protocols

This cURL command demonstrates how to perform cognitive retrieval using the REST API. It takes a context query and returns relevant information up to a specified limit.

```bash
curl -X POST http://localhost:8475/api/activate \
  -H "Authorization: Bearer mk_xK9m..." \
  -H "Content-Type: application/json" \
  -d '{"context": "what security events happened?", "limit": 5}'
```

--------------------------------

### Structured Logging

Source: https://muninndb.com/docs/observability

MuninnDB outputs structured JSON logs, compatible with various log aggregators.

```APIDOC
## Structured Logging

All log output is structured JSON via Go's stdlib `slog`. Pipe to any log aggregator (Loki, CloudWatch, Datadog).

### Example Log Entry
```json
{"time":"2026-02-21T10:00:00Z","level":"INFO","msg":"activate","vault":"default","duration_ms":12,"results":5,"context_len":24}
```
```

--------------------------------

### Authentication

Source: https://muninndb.com/docs/api/rest

Authenticated endpoints require a Bearer token in the `Authorization` header. Tokens are created via `muninn init` or the admin API. Public endpoints do not require authentication.

```APIDOC
## Authentication

Authenticated endpoints require a Bearer token in the `Authorization` header.

```
Authorization: Bearer mk_xK9m...
```

Public endpoints (`/health`, `/ready`, `/workers`, `/hello`) require no auth. All vault operations require a Bearer token.
```

--------------------------------

### MuninnDB MCP Connection

Source: https://muninndb.com/docs/api/mcp

Details on how to connect to the MuninnDB MCP server, including the default port, endpoint, and authentication methods.

```APIDOC
## MuninnDB MCP Connection Details

### Description
The MCP server listens on port `8750` by default. The endpoint is `http://localhost:8750/mcp` (JSON-RPC 2.0 over HTTP).

### Authentication
Auth is optional. Set a Bearer token with `--mcp-token` or configure one via `muninn init`.

### Rate Limiting
The MCP server enforces 100 requests/sec sustained, 200 burst. This is per-server, not per-tool.
```

--------------------------------

### muninn_session

Source: https://muninndb.com/docs/api/mcp

Provides a summary of recent activity within a vault since a specified timestamp.

```APIDOC
## POST /mcp/muninn_session

### Description
Get a summary of recent activity since a given time — activations, writes, and link events.

### Method
POST

### Endpoint
`http://localhost:8750/mcp`

### Parameters
#### Request Body
- **since** (string) - Required - ISO 8601 timestamp (e.g. "2025-01-15T09:00:00Z")
- **vault** (string) - Optional - Vault name (default: "default")

### Request Example
```json
{
  "jsonrpc": "2.0",
  "method": "muninn_session",
  "params": {
    "since": "2023-10-26T12:00:00Z",
    "vault": "my_vault"
  },
  "id": 1
}
```

### Response
#### Success Response (200)
- **result** (object) - Summary of recent activity.
- **error** (object) - Contains error details if the operation failed.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "result": {
    "activations": 15,
    "writes": 5,
    "links": 2
  },
  "id": 1
}
```
```

--------------------------------

### Trigger Manual Cluster Failover

Source: https://muninndb.com/docs/clustering

Initiate a graceful failover of the cluster Cortex node using the CLI command. This is useful for planned maintenance on the current Cortex.

```bash
# Trigger a manual election (graceful handoff)
muninn cluster failover --yes
```