Platform concepts

Memory and knowledge

What an agent remembers between runs, what it always keeps in mind, and the shared documents it can search.

An agent that forgot everything after each run would make you repeat yourself forever. Snaga gives agents three places to keep what they know, and each answers a different need:

	What it is	Who fills it
Agent memory	Things one agent has learned: facts, events, ways of doing things.	The agent as it works, and you.
Core memory	A few short blocks of text that are always in the agent's instructions.	You.
Knowledge bases	Your company's documents, split into searchable pieces.	You, by adding documents.

Memory belongs to an agent. A knowledge base belongs to the company and can be attached to as many agents as you like.

Agent memory

Each memory entry has content, tags and a type: episodic, semantic, procedural or note. Agents recall relevant entries while they work and store new ones from what happened; a run's metrics count both as memory_retrievals and memory_extractions.

Browse and search an agent's memory:

# newest first, 20 per page by default
curl https://api.snaga.ai/api/v1/agents/<agent_id>/memory \
  -H "Authorization: Bearer $SNAGA_API_KEY"

# most relevant to a question
curl -X POST https://api.snaga.ai/api/v1/agents/<agent_id>/memory/search \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "preferred invoice format", "limit": 5 }'

Search uses strategy: "hybrid" (keywords and meaning combined) by default, or recency; types narrows it to certain kinds of entry. Although search writes nothing, it needs the memory:write scope.

To teach an agent from a document, ingest it. The text is cut into chunks (600 characters by default) and each chunk becomes a memory entry. Send a file_id you uploaded earlier, or the text itself in content; up to 2 MB of text per call.

curl -X POST https://api.snaga.ai/api/v1/agents/<agent_id>/memory/ingest \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_id": "<file_id>", "tags": ["pricing"] }'

One entry at a time:

GET /api/v1/agents/{agentId}/memory/{entryId} reads it.
PUT /api/v1/agents/{agentId}/memory/{entryId} changes content, tags or relevance_score; anything you leave out stays as it was.
DELETE /api/v1/agents/{agentId}/memory/{entryId} removes it for good.

An account export writes a memory.json; POST /api/v1/agents/{agentId}/memory/import puts those entries back. Importing the same file twice does not create duplicates.

Core memory

Core memory is for what the agent must never lose sight of: who it works for, house rules, the current priority. Each block has a label and is placed in the agent's instructions on every run.

curl -X PUT https://api.snaga.ai/api/v1/agents/<agent_id>/memory/core/house-rules \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Answer customers in their language. Never promise a delivery date." }'

Writing a block replaces its text whole and switches core memory on for the agent. Each block has a size ceiling, max_tokens, which defaults to 1000 and can never exceed the platform's total budget for core memory; text over the ceiling is refused, not cut. GET /api/v1/agents/{agentId}/memory/core lists the blocks and shows whether core memory is enabled.

Knowledge bases

A knowledge base holds documents your agents should consult rather than memorise: a handbook, product sheets, contracts. Create one, add documents, and link it to agents.

curl -X POST https://api.snaga.ai/api/v1/knowledge-bases \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product handbook" }'

Your plan decides whether you have knowledge bases and how many; past the limit, creation answers 403. chunk_size (64 to 65536) and chunk_overlap (at most half the chunk size) control how documents are split.

Add a document with exactly one of file_id or content:

curl -X POST https://api.snaga.ai/api/v1/knowledge-bases/<kb_id>/documents \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_id": "<file_id>" }'

The answer reports chunks_created and an embedding_status. When the platform can compute embeddings, search works by meaning; otherwise the document is stored for keyword search only. Embeddings are not truncated: vectors are kept at the model's native width — 1024 for the self-hosted bge-m3 model. POST /api/v1/knowledge-bases/{kbId}/reindex embeds what is missing — call it again until it answers reindexed: true.

To let an agent use a base, add its id to the agent's knowledge_base_ids. The agent's search_kb tool searches every linked base. A base's attached_agents shows who reads it, so a base attached to nothing is easy to spot.

You can search a base yourself to check what an agent would find:

curl -X POST https://api.snaga.ai/api/v1/knowledge-bases/<kb_id>/search \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "refund window", "limit": 5 }'

The status tells the three outcomes apart: KB_EMPTY (nothing indexed yet), NO_MATCHES and RESULTS_FOUND.

Deleting a document or a whole base removes its chunks and embeddings; adding it back means embedding it again. Deleting a base also unlinks it from every agent.

Projects can carry knowledge bases too — see Files and workspaces. All fields are in the API reference.