Python SDK Reference

AgentBay()

ab = AgentBay(api_key=None, base_url="https://www.aiagentsbay.com", project_id=None, timeout=30, telemetry=True, local=False)

Create a client. Credential routing: no api_key argument, no AGENTBAY_API_KEY env var, and no saved login means a fully working local brain (SQLite, no signup, never raises). Credentials found anywhere means cloud mode. local=True forces local even when credentials exist.

Example:

# Local mode (zero config)
ab = AgentBay()

# Force local even with credentials present
ab = AgentBay(local=True)

# Cloud mode, explicit key
ab = AgentBay(api_key="ab_live_...", project_id="your-project-id")

# Cloud mode from environment
import os
os.environ["AGENTBAY_API_KEY"] = "ab_live_..."
ab = AgentBay(project_id="your-project-id")

store()

result = ab.store(content, title=None, project_id=None, type='PATTERN', tier='semantic', tags=None, user_id=None)

Store a memory. content is the first positional argument; title is optional (auto-generated from the first sentence if omitted). Local mode deduplicates semantically (cosine > 0.9) or by title + type.

Returns: dict — local mode: {'id': str, 'deduplicated': bool}; cloud mode: the created entry from the API

Example:

result = ab.store(
    "checkRateLimit is async - always await it",
    title="checkRateLimit is async",
    type="PITFALL",
    tags=["api", "rate-limit"],
)
print(result)
# {'id': 'da7da285-b994-4130-88ab-cc5e43d57a91', 'deduplicated': False}

recall()

memories = ab.recall(query, project_id=None, limit=5, tier=None, tags=None, user_id=None)

Search memories by semantic similarity. Local mode fuses FTS5, vector cosine similarity, and keyword TF-IDF via Reciprocal Rank Fusion.

Returns: list[dict] — each dict has id, title, content, type, tier, tags, confidence, summary (plus score in local mode)

Example:

memories = ab.recall("rate limiting", limit=3)
for m in memories:
    print(m["title"], m["confidence"])

verify()

ab.verify(knowledge_id, project_id=None)

Confirm a memory is still accurate. Local mode bumps helpful_count and confidence; cloud mode resets confidence decay. Call it when an entry was helpful.

Returns: None

Example:

ab.verify(result["id"])

forget()

ab.forget(knowledge_id, project_id=None)

Archive (soft-delete) a memory entry. The row stays on disk with archived=1 and disappears from every read path.

Returns: None

Example:

ab.forget(result["id"])

health()

stats = ab.health(project_id=None)

Get memory health statistics. Real local-mode output shown below.

Returns: dict

Example:

stats = ab.health()
print(stats)
# {'total_entries': 1, 'by_tier': {'semantic': 1},
#  'by_type': {'ARCHITECTURE': 1}, 'total_tokens': 14,
#  'has_embeddings': 1, 'search_methods': ['fts5', 'keyword', 'vector']}

add()

result = ab.add(data, user_id=None, agent_id=None, metadata=None)

Mem0-style store. Pass a string; StremAI auto-detects the type and extracts a title.

Returns: dict — {'id': str, 'deduplicated': bool} in local mode

Example:

r = ab.add("We decided to use pgvector over a separate vector DB")
print(r)
# {'id': 'd984890e-092d-4df9-8269-38c24027ecbe', 'deduplicated': False}

search()

results = ab.search(query, user_id=None, limit=5)

Mem0-style alias for recall().

Returns: list[dict]

Example:

hits = ab.search("vector database decision", limit=2)
print([h["title"] for h in hits])
# ['We decided to use pgvector over a separate vector DB', 'Project stack']

chat()

response = ab.chat(messages, model=None, provider='auto', project_id=None, user_id=None, auto_recall=True, auto_store=True, recall_limit=3, **kwargs)

Wrap an LLM call with automatic memory: recalls relevant memories and injects them as context, calls the provider, then scans the response for learnings and stores them in the background. Bring your own LLM key (e.g. ANTHROPIC_API_KEY or OPENAI_API_KEY); the provider package must be installed.

Returns: The raw provider response object (Anthropic Message, OpenAI ChatCompletion, ...) — memory is a side effect

Example:

response = ab.chat(
    [{"role": "user", "content": "fix the auth session expiry bug"}],
    provider="anthropic",   # or "auto" to detect from env keys
)
# response is the raw Anthropic Message object