About this tool

The IteraTools Vector Memory Upsert API stores text documents as vector embeddings (OpenAI text-embedding-3-small, 1536 dimensions) in a persistent SQLite database. Each document is identified by a namespace + id pair. If the document already exists it's updated. Namespaces are automatically isolated per API key, so your data stays private. Perfect for building RAG (Retrieval-Augmented Generation) pipelines, agent long-term memory, knowledge bases, and semantic search stores.

Quick Start

curl -X POST https://api.iteratools.com/memory/upsert \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "my-agent",
    "id": "fact-1",
    "text": "The user prefers dark mode and uses Python.",
    "metadata": {"source": "preferences", "date": "2026-01-01"}
  }'

Response

{
  "ok": true,
  "data": {
    "id": "fact-1",
    "namespace": "my-agent",
    "tokens": 12,
    "dimensions": 1536
  }
}

Python Example

import requests

def memory_upsert(namespace: str, doc_id: str, text: str, api_key: str, metadata: dict = None) -> dict:
    res = requests.post(
        "https://api.iteratools.com/memory/upsert",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"namespace": namespace, "id": doc_id, "text": text, "metadata": metadata or {}}
    )
    return res.json()

# Store user facts for an agent
facts = [
    ("fact-1", "User prefers dark mode and uses Python."),
    ("fact-2", "User timezone is UTC-3 (Brazil)."),
    ("fact-3", "User is building a rhythm game called Sambamancer."),
]
for doc_id, text in facts:
    result = memory_upsert("user-profile", doc_id, text, "YOUR_KEY")
    print(f"Stored {doc_id}: {result['data']['tokens']} tokens")

Request Body

namespace	string (required)	Logical namespace (e.g. my-agent, user-facts)
id	string (required)	Unique document ID (upserted if exists)
text	string (required)	Text content to embed and store
metadata	object (optional)	Key-value metadata for filtering or display

Details

Endpoint	POST /memory/upsert
Price	$0.003 / request
Embedding model	OpenAI text-embedding-3-small (1536 dims)
Isolation	Per API key (namespaces prefixed automatically)
Auth	Bearer token or x402 micropayment
Base URL	https://api.iteratools.com

Use Cases

🤖 Agent long-term memory — store facts about users across sessions
📚 RAG knowledge bases — index docs for semantic retrieval
🔎 Semantic search — find similar content by meaning, not keywords
🧩 Multi-agent context — share structured memory between agents
💬 Chat history indexing — store conversation chunks for retrieval

Full Documentation Memory Search → Browse All Tools