MemoryBase

1. Every SDK, plus the agent tools

MemoryBase is a first-class part of boxxkite-client in all four SDKs — Python, JavaScript, Go, and Rust all speak the same /v1/memory* REST surface directly, not just the Python agent-tools wrapper.

from boxxkite_client import BoxxkiteClient

client = BoxxkiteClient(base_url="https://api.boxxkite.com", api_key="bxk_live_...")

mem = client.remember("The user prefers TypeScript over JavaScript.")
hits = client.recall("TypeScript")
profile = client.memory_profile()
client.forget_memory(mem["id"])

The MCP serveralso exposes these same five operations directly to any MCP-compatible client (Claude Code, Claude Desktop, Codex, Cursor) — no extra flag needed, they're part of its standard 31-tool surface. The server's own instructions steer a connecting agent toward calling recall/memory_profile early in a task and remember when it learns something durable, rather than relying on the agent to discover the tools on its own.

The Python agent-tools wrapper (boxxkite.tools, the root package used inside a sandboxed agent loop) is separate from the SDK above — it wraps the same REST surface as five LLM tool specs an agent can call directly:

from boxxkite.tools import create_sandbox_tool_specs

specs = create_sandbox_tool_specs(
    sandbox_manager=manager,
    enable_memory_tools=True,
    hosted_api_key="bxk_live_...",       # required -- no unauthenticated memory endpoint
    hosted_base_url="https://api.boxxkite.com",
)

account_id is derived from the API key server-side and is never accepted as a tool argument, request field, or SDK parameter. scope partitions memories within an account (for example, per project) but is not an authorization boundary by itself — every read, search, and mutation is still filtered by the authenticated account.

2. The five agent tools

• remember(content, kind, scope, metadata) — store one fact directly.
• ingest_memory(content, scope, source_session_id) — extract bounded, atomic memories from a document or session. Works without any model provider configured.
• recall(query, scope, limit) — search stored memories.
• memory_profile(scope, limit) — separates stable, long-lived facts from recently-touched ones.
• forget_memory(memory_id) — permanently deletes one memory. This is a real delete, not a soft-delete that could be accidentally recalled later.

Each tool call returns JSON. A failed call returns a string starting with Memory error: instead of raising, so a single memory-service hiccup does not crash an agent turn. Every SDK exposes the same five operations plus the rest of the REST surface below (list, get, relations, export/import) as typed methods instead of tool specs.

3. Or call the REST API directly

# Remember a fact
POST /v1/memory
Authorization: Bearer bxk_live_...
Content-Type: application/json

{ "content": "The user prefers TypeScript over JavaScript.", "kind": "fact", "scope": "default" }

# Search
GET /v1/memory/search?q=TypeScript&scope=default

# Stable vs. recent context
GET /v1/memory/profile?scope=default

# Permanently delete
DELETE /v1/memory/{memory_id}

Also available: GET /v1/memory (list), GET /v1/memory/{id} (read one), GET /v1/memory/{id}/relations (related memories), and GET /v1/memory/export / POST /v1/memory/importfor backup and migration between deployments — every SDK above exposes each of these as a typed method too (for example Python's list_memories()/get_memory()/memory_relations()/export_memories()/import_memories()).

4. Retrieval: zero dependencies by default

BOXXKITE_MEMORY_EMBEDDINGS_ENABLED defaults to false. A fresh self-hosted install gets full-text lexical search immediately — no API key, no model server, no extra setup.

Turning embeddings on for semantic recall defaults to microsoft/harrier-oss-v1-0.6b, an open-source model served by the standalone memory-model-server in this repo. It keeps PyTorch and model weights out of the control-plane process and auto-selects Apple MPS, CUDA, or CPU:

cd memory-model-server
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
BOXKITE_EAGER_LOAD=true .venv/bin/uvicorn app:app --host 127.0.0.1 --port 8000

A managed provider (Gemini Embedding 2) is available as an explicit opt-in (BOXXKITE_MEMORY_EMBEDDING_PROVIDER=gemini) for anyone who wants it — it is never the default, and self-hosted deployments never send memory content to it unless you configure it yourself.