API Reference

Authentication

All API requests require authentication using your secret API key. Include it in the Authorization header as a Bearer token:

Authorization: Bearer tb-your_api_key_here

Alternatively, you can use the x-api-key header:

x-api-key: tb-your_api_key_here

Base URL for all endpoints:

https://onboarding.tokyobrain.ai

Core Endpoints

POST /v1/store

Saves a new memory or system state into the agent's dedicated namespace.

Request Body:

{
  "document": "Completed the integration of the Stripe payment module.",
  "track": "history",
  "metadata": {
    "project": "myapp",
    "priority": "high"
  }
}

Response (202 Accepted):

{
  "ok": true,
  "id": "01JQXYZ123ABC",
  "status": "queued"
}

Writes are async by default for performance. Use "sync": true for immediate confirmation.

cURL example:

curl -X POST https://onboarding.tokyobrain.ai/v1/store \
  -H "Authorization: Bearer tb-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "Project uses FastAPI + PostgreSQL",
    "track": "state",
    "metadata": {"project": "myapp", "priority": "high"}
  }'

POST /v1/recall

Retrieves semantically relevant memories based on the agent's current context. Queries pass through the full 10-layer recall pipeline.

Request Body:

{
  "query": "What payment gateways have we discussed?",
  "format": "structured",
  "topK": 5
}

Response -- format: "structured" (200 OK):

{
  "results": [
    "[2026-04-03 | myapp | high] Completed Stripe payment module integration.",
    "[2025-12-01 | myapp | medium] Discussed PayPal but decided to hold off."
  ],
  "_latency": 234
}

Response -- format: "raw" (200 OK):

{
  "hot": [],
  "warm": [
    {
      "id": "01JQXYZ123ABC",
      "document": "Completed Stripe payment module integration.",
      "metadata": {
        "ts": 1743638400000,
        "project": "myapp",
        "priority": "high"
      },
      "distance": 0.12,
      "collection": "nexus_knowledge"
    }
  ],
  "_latency": 234
}

cURL example:

curl -X POST https://onboarding.tokyobrain.ai/v1/recall \
  -H "Authorization: Bearer tb-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what framework does this project use?",
    "format": "structured",
    "topK": 3
  }'

POST /v1/forget

Performs hard physical deletion across all three storage layers (Hot/Warm/Cold). GDPR compliant.

Method A: Delete by specific IDs

{
  "ids": ["01JQXYZ123ABC", "01JQXYZ456DEF"]
}

Method B: Delete by metadata filter

{
  "where": {
    "project": "old-project"
  }
}

Method C: Delete by collection + filter

{
  "collection": "nexus_daily",
  "where": {
    "ts": {"$lt": 1700000000000}
  }
}

Response (200 OK):

{
  "ok": true,
  "deleted": {
    "hot": 0,
    "warm": 12,
    "cold": 3
  }
}

GET /v1/health

Returns system status and your usage for the current billing cycle. No authentication required.

Response (200 OK):

{
  "ok": true,
  "version": "3.0.0",
  "hot": "PONG",
  "warm": "OK",
  "cold": "OK",
  "usage": {
    "api_calls_this_month": 1450,
    "storage_count": 8234,
    "limit": {
      "recall": 10000,
      "store": 10000
    }
  }
}

cURL example:

curl https://onboarding.tokyobrain.ai/v1/health

GET /v1/health/mood

Returns the brain's current emotional state. The mood reflects real-time processing load, entropy levels, and recent interaction patterns.

Response (200 OK):

{
  "mood": "curious",
  "emoji": "🤔",
  "intensity": 0.72,
  "description": "Actively processing new information across multiple topics",
  "stats": {
    "recent_stores": 14,
    "recent_recalls": 38,
    "entropy_level": 0.45,
    "uptime_hours": 127.3
  }
}

cURL example:

curl https://onboarding.tokyobrain.ai/v1/health/mood \
  -H "Authorization: Bearer tb-your_api_key_here"

GET /v1/entropy

Returns the current knowledge stability status. The entropy monitor tracks topic volatility in a 20-minute sliding window and fires alerts when topics change rapidly.

Response (200 OK):

{
  "status": "ELEVATED",
  "current_buffer_size": 12,
  "latest_alert": {
    "topic": "deployment-config",
    "entropy_score": 0.87,
    "triggered_at": "2026-04-06T14:32:00Z",
    "message": "Rapid topic shifts detected in deployment-config"
  },
  "mood": {
    "mood": "anxious",
    "emoji": "😰",
    "intensity": 0.85
  }
}

cURL example:

curl https://onboarding.tokyobrain.ai/v1/entropy \
  -H "Authorization: Bearer tb-your_api_key_here"

POST /v1/audit

Returns the full mutation audit log. Every memory creation, auto-merge, and guardian veto is recorded with a cryptographic signature for tamper-proof accountability.

Request Body:

{
  "limit": 50
}

Response (200 OK):

{
  "total": 1247,
  "entries": [
    {
      "action": "create",
      "target_id": "01JQXYZ123ABC",
      "actor": "user",
      "after_hash": "sha256:a1b2c3d4e5f6...",
      "_signature": "0x3a4b5c6d...",
      "_signer": "0x7e8f9a0b...",
      "timestamp": "2026-04-06T10:15:30Z"
    },
    {
      "action": "auto_merge",
      "target_id": "01JQXYZ456DEF",
      "actor": "mra_tribunal",
      "after_hash": "sha256:f6e5d4c3b2a1...",
      "_signature": "0x9a0b1c2d...",
      "_signer": "0x7e8f9a0b...",
      "timestamp": "2026-04-06T03:05:12Z"
    },
    {
      "action": "guardian_veto",
      "target_id": "01JQXYZ789GHI",
      "actor": "mra_tribunal",
      "after_hash": "sha256:1a2b3c4d5e6f...",
      "_signature": "0x2d3e4f5a...",
      "_signer": "0x7e8f9a0b...",
      "timestamp": "2026-04-06T03:02:45Z"
    }
  ]
}

cURL example:

curl -X POST https://onboarding.tokyobrain.ai/v1/audit \
  -H "Authorization: Bearer tb-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50}'

POST /v1/mutations

Returns the full mutation history for a specific memory. Useful for tracing how a memory evolved over time through merges, edits, and tribunal decisions.

Request Body:

{
  "target_id": "01JQXYZ123ABC"
}

Response (200 OK):

{
  "target_id": "01JQXYZ123ABC",
  "mutations": [
    {
      "action": "create",
      "actor": "user",
      "after_hash": "sha256:a1b2c3d4e5f6...",
      "_signature": "0x3a4b5c6d...",
      "timestamp": "2026-04-05T09:00:00Z"
    },
    {
      "action": "auto_merge",
      "actor": "mra_tribunal",
      "after_hash": "sha256:b2c3d4e5f6a1...",
      "_signature": "0x4b5c6d7e...",
      "timestamp": "2026-04-06T03:05:12Z"
    }
  ],
  "count": 2
}

cURL example:

curl -X POST https://onboarding.tokyobrain.ai/v1/mutations \
  -H "Authorization: Bearer tb-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"target_id": "01JQXYZ123ABC"}'

POST /v1/skeptic

Returns the contradiction alert history from the Skeptic persona of the MRA Tribunal. When new information contradicts existing memories, the Skeptic flags it for review.

Response (200 OK):

{
  "alerts": [
    {
      "action": "contradiction_detected",
      "target_id": "01JQXYZ123ABC",
      "contradicts": "01JQXYZ456DEF",
      "pattern": "User previously stated PostgreSQL, now claims MySQL"
    },
    {
      "action": "contradiction_detected",
      "target_id": "01JQXYZ789GHI",
      "contradicts": "01JQXYZ012JKL",
      "pattern": "Deployment target changed from AWS to GCP without explicit decision"
    }
  ],
  "count": 2
}

cURL example:

curl -X POST https://onboarding.tokyobrain.ai/v1/skeptic \
  -H "Authorization: Bearer tb-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /v1/verify

Verifies a cryptographic signature against the brain's signing wallet. Use this to independently confirm that an audit entry or memory hash was genuinely signed by the system.

Request Body:

{
  "message": "sha256:a1b2c3d4e5f6...",
  "signature": "0x3a4b5c6d..."
}

Response (200 OK):

{
  "valid": true,
  "recovered_address": "0x7e8f9a0b..."
}

cURL example:

curl -X POST https://onboarding.tokyobrain.ai/v1/verify \
  -H "Authorization: Bearer tb-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "sha256:a1b2c3d4e5f6...",
    "signature": "0x3a4b5c6d..."
  }'

Advanced Features

Multimodal Memory

Tokyo Brain can accept rich sensory_inputs alongside text. The system synthesizes a multimodal narrative for embedding, combining context from multiple input channels.

{
  "document": "Team standup meeting notes",
  "sensory_inputs": {
    "text_transcript": "We decided to ship v2 by Friday...",
    "audio_features": {
      "speaker_id": "alice",
      "tone": "confident"
    },
    "visual_features": {
      "scene_context": "conference room",
      "facial_expression": "focused"
    }
  }
}

The brain fuses these signals into a single enriched memory entry with higher emotional salience and richer entity extraction.

Confidence Scoring

Every memory is automatically classified with a confidence score based on how it was acquired:

V2 (Night Cycle): During the daily Night Cycle at 3:00 AM UTC, an LLM deep audit re-evaluates inferred memories and may promote or demote their confidence scores.

Cryptographic Cortex

Every memory stored in Tokyo Brain is protected by a dual-layer cryptographic system:

• SHA-256 Hash -- Content integrity fingerprint. Any tampering changes the hash.
• Wallet Digital Signature -- Each hash is signed by the brain's private key, creating an unforgeable audit trail.

Verify any signature independently via the /v1/verify endpoint. This makes every mutation provably traceable.

Safety Triangle

Three interlocking safety systems protect the brain from harmful mutations:

Python SDK

The official Python SDK wraps all endpoints and handles authentication, retries, and error handling.

Installation

pip install tokyo-brain

Quick Start

from tokyo_brain import TokyoBrain

brain = TokyoBrain(api_key="tb-your_api_key_here")

# Store a memory
brain.store("Oscar rode his bike for the first time today")

# Store with metadata and track
brain.store(
    "Project uses FastAPI + PostgreSQL",
    track="state",
    metadata={"project": "myapp", "priority": "high"}
)

# Recall with full 10-layer pipeline
results = brain.recall("What happened with Oscar recently?")
for r in results:
    print(r)

# Recall with options
results = brain.recall(
    "what framework?",
    format="structured",
    top_k=3
)

# Forget by metadata filter
brain.forget(where={"project": "old-project"})

# Forget by IDs
brain.forget(ids=["01JQXYZ123ABC"])

Environment Variable

You can also set your API key via environment variable instead of passing it directly:

export TOKYO_BRAIN_API_KEY=tb-your_api_key_here

from tokyo_brain import TokyoBrain

brain = TokyoBrain()  # reads from TOKYO_BRAIN_API_KEY

PyPI: tokyo-brain

LangChain Integration

Already using LangChain? Swap in Tokyo Brain memory with two lines. Your chain code stays exactly the same.

# Before (goldfish memory):
from langchain.memory import ConversationBufferMemory
memory = ConversationBufferMemory()

# After (10-layer brain with subconscious):
from tokyo_brain.langchain import TokyoBrainMemory
memory = TokyoBrainMemory(api_key="tb-your_api_key_here")
# That's it. Your chain code stays exactly the same.

As a Retriever (RAG chains)

from tokyo_brain.langchain import TokyoBrainRetriever

retriever = TokyoBrainRetriever(api_key="tb-your_api_key_here", top_k=5)

# Use in any LangChain RetrievalQA chain
from langchain.chains import RetrievalQA
from langchain_openai import ChatOpenAI

qa = RetrievalQA.from_chain_type(
    llm=ChatOpenAI(),
    retriever=retriever
)

As ChatMessageHistory (persistent sessions)

from tokyo_brain.langchain import TokyoBrainChatHistory

history = TokyoBrainChatHistory(api_key="tb-your_api_key_here")

# Works with RunnableWithMessageHistory, ConversationChain, etc.

Framework Adapters

Tokyo Brain provides drop-in adapters for popular AI agent frameworks. Each adapter wraps the full API and handles authentication, retries, and format conversion automatically.

CrewAI

from tokyo_brain.crewai import TokyoBrainCrewMemory

memory = TokyoBrainCrewMemory(api_key="tb-your_api_key_here")

# Use as crew memory backend
from crewai import Crew
crew = Crew(memory=memory, agents=[...], tasks=[...])

AutoGen

from tokyo_brain.autogen import TokyoBrainAutoGenMemory

memory = TokyoBrainAutoGenMemory(api_key="tb-your_api_key_here")

# Plug into AutoGen agents
from autogen import AssistantAgent
agent = AssistantAgent("assistant", memory=memory)

LlamaIndex

from tokyo_brain.llamaindex import TokyoBrainRetriever

retriever = TokyoBrainRetriever(api_key="tb-your_api_key_here")

# Use as a LlamaIndex retriever in any query engine
from llama_index.core.query_engine import RetrieverQueryEngine
engine = RetrieverQueryEngine(retriever=retriever)

Error Codes

Error response format:

{
  "ok": false,
  "error": "unauthorized",
  "message": "Invalid or missing API key. Keys start with tb-"
}

Rate Limits

When you hit your monthly limit, the API returns 429 with a Retry-After header. Upgrade your plan or wait for the next billing cycle.

Check your current usage at any time via the /v1/health endpoint.

Architecture

Tokyo Brain uses a three-tier memory architecture. All data is encrypted at rest with AES-256-GCM envelope encryption.

Store Path

Input -> Sanitizer -> Emotional Salience -> Fact Extraction
     -> BGE-m3 Embedding -> ChromaDB -> Entropy Monitor

Recall Path (10-Layer Pipeline)

Query -> Expansion -> Entity Link -> Temporal Parse
     -> Multi-Collection Search -> Curated Boost -> Time Decay
     -> Emotional Boost -> Temporal Filter -> Re-rank -> Dedup

Background Processes

For a deep dive into the architecture and benchmark results, read our engineering blog post.