Documentation

Integrate persistent memory into your AI agent in about 5 minutes. Create a project and API key from your dashboard, then start calling the API below.

1. Authenticate

Every request to /api/v1/* requires a Bearer API key, generated from Dashboard → API Keys. Keys are shown once at creation time and stored hashed — treat them like a password.

2. Store a memory

curl -X POST https://your-contextforge-host/api/v1/memories \
  -H "Authorization: Bearer cf_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "agent_id": "nova-assistant",
    "content": "I prefer vegetarian restaurants and usually want meetings after 3 PM.",
    "metadata": { "channel": "chat" }
  }'

3. Retrieve relevant context

curl -X POST https://your-contextforge-host/api/v1/context \
  -H "Authorization: Bearer cf_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "query": "Recommend dinner options tonight.",
    "max_memories": 8,
    "token_budget": 1000
  }'

4. Or use the Python SDK

pip install contextforge

import contextforge

contextforge.configure(api_key="cf_live_xxxxxxxxxxxxxxxxxxxx", base_url="https://your-contextforge-host")

# Store a memory -- ContextForge decides what's actually worth remembering
result = contextforge.remember(
    user_id="user_123",
    agent_id="nova-assistant",
    content="I prefer vegetarian restaurants and usually eat around 7 PM.",
)
for m in result.stored:
    print(m.memory_type, m.content, m.reason)

# Retrieve only what's relevant to the current task
context = contextforge.get_context(
    user_id="user_123",
    query="Recommend dinner options tonight.",
)
print(context.compact_context)
print("tokens saved:", context.stats.tokens_saved_estimated)

# Forget a specific memory, or everything for a user
contextforge.forget(memory_id=result.stored[0].memory_id)
contextforge.forget_user(user_id="user_123")

API reference

POST/api/v1/memoriesAnalyze content with Gemini and store durable memories worth remembering.

GET/api/v1/memoriesList memories, filterable by user, agent, type, date, importance.

DELETE/api/v1/memories/{id}Delete a single memory.

DELETE/api/v1/memoriesDelete every memory for a given user_id (body).

POST/api/v1/contextSemantic retrieval + Gemini reranking + token-budget-aware context construction.

POST/api/v1/health-agentRun the AI Memory Health Agent analysis for a project.

Memory types

profile, preference, fact, task, decision, conversation_summary, relationship, instruction, episodic, custom. Gemini assigns these automatically, or pass memory_type explicitly to override.

Errors

Errors are returned as { "error": { "code": "...", "message": "..." } } with an appropriate HTTP status: 401 invalid/missing API key, 402 plan memory limit reached, 429 rate limited, 400 invalid request body.