Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bsyncs.com/llms.txt

Use this file to discover all available pages before exploring further.

Cost: 5 operations per call

​
POST /brain/ingest

Processes a piece of text through the full ingestion pipeline:
  1. Deduplication — skips the text if a near-identical chunk already exists (cosine similarity ≥ 0.92)
  2. Graph extraction — extracts entities and relationships via spaCy (default) or LLMGraphTransformer (when use_llm_extraction: true)
  3. Semantic storage — writes graph triples to Neo4j with embeddings for vector index lookup
  4. Episodic storage — chunks the text via SemanticChunker and stores embeddings in Qdrant
  5. Working memory — updates the session rolling topic vector in Redis (if session_id provided)

​
Request body

{
  "text": "Sarah Jenkins is the Lead Software Engineer at Acme Corp.",
  "persona": "shared",
  "source": "user",
  "session_id": "session-abc",
  "use_llm_extraction": false,
  "metadata": {
    "document_id": "doc-001",
    "tags": ["team", "personnel"]
  }
}
FieldTypeRequiredDefaultDescription
textstring✓—The text to ingest. Minimum 1 character.
personastring"shared"Memory sub-namespace within your user account.
sourcestring"user"Origin label: "user", "assistant", or "document". Affects confidence scoring.
session_idstringnullEnables working memory update for this session.
use_llm_extractionbooleanfalseUse LLMGraphTransformer (GPT-4.1) instead of spaCy for richer graph extraction. Costs more.
metadataobjectnullArbitrary key-value pairs stored alongside the memory.

​
Response

{
  "facts_ingested": 3,
  "episodic_chunks": 1,
  "entities_extracted": 2,
  "triples_extracted": 3,
  "working_memory_updated": true,
  "msg": "Ingested 3 relations, 2 entities, 1 episodic chunks.",
  "latency_ms": 412.7
}
FieldTypeDescription
facts_ingestedintNumber of graph relationships stored in Neo4j.
episodic_chunksintNumber of vector chunks stored in Qdrant.
entities_extractedintNumber of entity nodes created or updated.
triples_extractedintSame as facts_ingested.
working_memory_updatedbooleanWhether the session topic vector was updated.
latency_msfloatTotal processing time in milliseconds.

​
Code examples

from atlas_mem import AtlasMem

brain = AtlasMem(api_key="atlas_...", base_url="https://api.bsyncs.com", user_id="user-123")

# Basic ingest
result = brain.add("Sarah Jenkins is the Lead Software Engineer at Acme Corp.")
print(result.entities_extracted)  # 2
print(result.triples_extracted)   # 3

# With LLM extraction (richer graph, higher cost)
result = brain.add(
    "The payment service uses Stripe for card processing and falls back to PayPal on failure.",
    source="document",
    metadata={"source_file": "architecture.md"},
)

​
Batch ingest — POST /brain/ingest/batch

For ingesting multiple texts efficiently in one call.
Cost: 5 ops × number of items. Batch cost is deducted atomically upfront.
{
  "items": [
    {
      "text": "Sarah Jenkins is the Lead Software Engineer at Acme Corp.",
      "persona": "shared",
      "source": "user"
    },
    {
      "text": "Acme Corp's primary database is PostgreSQL.",
      "persona": "shared",
      "source": "document"
    }
  ]
}
Batch size limits by tier:
TierMax batch size
Free5
Starter20
Pro50
Scale / Enterprise100

​
Tips

Enable use_llm_extraction: true for long-form documents (technical specs, architecture docs, meeting notes) where entity relationships are complex. Keep it disabled for short conversational turns — spaCy is sufficient and much faster.
Memories stored with source: "user" have higher confidence than source: "assistant" in conflict resolution. When two memories contradict each other for the same slot, the user-sourced one wins.
Any fields in metadata are stored alongside the vector. You can use them for custom filtering in direct API calls.