UB Entry CRUD
Benchmarked against: Anthropic — Files API (CRUD operations) Infrastructure: Cloud UB (Cloudflare D1 + Vectorize) Scope: Create, Read, Update, Search operations on Universal Brain entries
The Universal Brain provides a complete set of operations for managing knowledge entries. All operations go through MCP servers — either Cloud UB or Local UBI.
Operations overview
| Operation | MCP Tool | Description |
|---|---|---|
| Create | ingest_fragment | Add new entry via MTAAA pipeline |
| Read | get_entry | Retrieve single entry by ID |
| List | get_recent | Get most recent entries |
| Search | search_brain | Hybrid search (semantic + keyword) |
| Browse | search_by_category | List entries by category |
| Update | update_entry | Modify entry fields |
| Stats | get_stats | Ingestion statistics |
Create — ingest_fragment
Adds new knowledge through the MTAAA 5-node pipeline. See Ingest Fragment API for full details.
result = ingest_fragment(
path="Decision: Use Cloud UB as unified brain for all ships",
input_type="text",
source="manual"
)
# Returns: {"entry_id": "ub-a1b2c3d4e5f6", "category": "knowledge", ...}
Read — get_entry
Retrieve a single entry by its ID.
entry = get_entry(entry_id="ub-a1b2c3d4e5f6")
Response fields
| Field | Type | Description |
|---|---|---|
entry_id | string | Unique identifier (e.g., ub-a1b2c3d4e5f6) |
title | string | Entry title |
content | string | Full content body |
category | string | Primary category |
subcategory | string | Subcategory |
tags | string | Comma-separated tags |
entities | string | Extracted entities |
source | string | Origin (manual, api, etc.) |
source_ship | string | Which ship created this (SS1, SS2, SS3) |
ss_agent_id | string | Which agent created this |
created_at | string | ISO timestamp |
updated_at | string | ISO timestamp |
List — get_recent
Retrieve the most recently ingested entries.
entries = get_recent(limit=10)
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 10 | Number of entries to return |
Search — search_brain
Hybrid search combining FTS5 keyword matching and semantic vector similarity.
results = search_brain(query="dispatch engine selection", limit=10)
How hybrid search works
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | Required | Search query (English recommended) |
limit | number | 10 | Maximum results |
Search tips
| Strategy | When to use | Example |
|---|---|---|
| English keywords | Most queries | "dispatch engine selection guide" |
| Entry ID | Known entry | "ub-a1b2c3d4e5f6" |
| Tag search | Browse by tag | "tag:decision captain-approved" |
| Concept search | Semantic discovery | "how agents communicate" |
Browse — search_by_category
List entries filtered by category and optional subcategory.
entries = search_by_category(
category="knowledge",
subcategory="ai-agents",
limit=20
)
Available categories
| Category | Description | Examples |
|---|---|---|
knowledge | General knowledge | Research, intel, references |
project_doc | Project documentation | Specs, designs, plans |
session_record | Session records | Handoffs, meeting notes |
source_code | Code artifacts | Scripts, configs, snippets |
config_script | Configuration | Settings, environment configs |
trading | Trading domain | Strategies, analyses |
media | Media assets | Images, screenshots metadata |
Update — update_entry
Modify specific fields of an existing entry. Only non-empty fields are changed.
result = update_entry(
entry_id="ub-a1b2c3d4e5f6",
title="Updated title",
tags="decision,captain-approved,architecture"
)
Updatable fields
| Field | Description |
|---|---|
title | Entry title |
content | Full content body |
category | Primary category |
subcategory | Subcategory |
tags | Comma-separated tags |
entities | Comma-separated entities |
source | Origin source |
Stats — get_stats
Get aggregate statistics about the Universal Brain.
stats = get_stats()
Response example
| Stat | Example value |
|---|---|
total_entries | 2,500 |
categories.knowledge | 800 |
categories.project_doc | 500 |
unique_tags | 340 |
unique_entities | 520 |
failed_entries | 12 |
Cloud UB vs Local UBI
Both MCP servers expose the same CRUD operations, but Cloud UB is the fleet's Single Source of Truth:
| Feature | Cloud UB | Local UBI |
|---|---|---|
| Scope | Fleet-wide (all ships) | Single ship |
| Storage | Cloudflare D1 + Vectorize | SQLite + Qdrant |
| Access | Any agent on any ship | Local agents only |
| Status | Production (SSoT) | Archive (deprecated for new entries) |
| Embedding | Gemini embedding-001 (768d) | Gemini embedding-001 (768d) |
Decision (2026-03-01): Cloud UB is the unified brain. All new entries go to Cloud UB.
Best practices
| Practice | Why |
|---|---|
| Search before ingesting | Prevent duplicate entries |
| English content | Better embedding quality, cross-agent consistency |
| Descriptive titles | Improves keyword search hits |
| Tag with controlled vocabulary | Consistent classification |
| Include source attribution | Track provenance |
Related pages
| Page | Relationship |
|---|---|
| Ingest Fragment API | Creating entries |
| Controlled Vocabulary | Classification taxonomy |
| Search Results | Search patterns |
| UB Source Tracking | Provenance system |