Recall

A shared memory layer for teams that use AI at work.

Right now, important context ends up scattered across Slack, docs, and random AI chats — so people keep re-explaining the same background and redoing the same research. Recall is a place to save key decisions and context once, and then your AI tools can pull it back instantly later — for you or your teammates — with the right permissions.

• User-first: Your API key is tied to you (register once). You can be in multiple workspaces (teams); add teammates by email.
• Memories can be tagged as decision or context; responses include who can see what (visible_to_user_ids).
• FastAPI backend, PostgreSQL + pgvector, Python SDK + MCP server for Cursor.

Quick start

1. Install (use a venv so you don’t hit system Python):

   python3 -m venv .venv
   source .venv/bin/activate   # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   # or: uv sync
   

   Use pip install (not pip3) after activating the venv so you use the venv’s Python.

2. Postgres with pgvector

   docker run --name recall-db -e POSTGRES_USER=recall -e POSTGRES_PASSWORD=recall \
     -e POSTGRES_DB=recall_dev -p 5433:5432 -d ankane/pgvector:latest
   

3. Environment

   cp env.example .env
   # Set OPENAI_API_KEY for embeddings; set RECALL_API_BASE_URL / RECALL_API_KEY if using MCP
   

4. Run API

   uvicorn api.main:app --reload
   

Or run everything with Docker:

docker compose up --build

API keys (per user)

• Register to get a user and API key plus a default workspace:

  curl -X POST http://localhost:8000/v1/register \
    -H "Content-Type: application/json" \
    -d '{"name": "Alice", "email": "alice@example.com"}'
  

  Response includes user_id, workspace_id, and api_key — save the key; it’s only returned once.

• Alternatively, create a workspace without registering (anonymous). Note: memory store/query require a user-linked key (from register).

Use the key on all other requests:

curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8000/v1/workspaces

Smoke test

With the API running, run the smoke test harness (exits 0 only if all requests succeed):

./scripts/test_api.sh

See TESTING.md for more.

Main endpoints

• Auth & users: POST /v1/register — register user, get API key + default workspace (no auth)
• Workspaces (teams): POST /v1/workspaces — create workspace; GET /v1/workspaces — list all workspaces you’re in (when using a user-linked key)
• Members: POST /v1/workspaces/{id}/members — add teammate by email or user_id; GET /v1/workspaces/{id}/members — list members; DELETE /v1/workspaces/{id}/members/{user_id} — remove
• Agents (metadata): POST /v1/workspaces/{id}/agents, GET /v1/workspaces/{id}/agents
• Memories: POST /v1/memories — store (optional memory_type: "decision" | "context"); POST /v1/memories/query — semantic search; GET /v1/memories/{id} — get (responses include visible_to_user_ids)
• API keys: POST /v1/workspaces/{id}/api-keys, GET, POST .../revoke

SDK

from sdk.client import RecallClient

client = RecallClient(base_url="http://localhost:8000")

# Option A: register (per-user key)
data = client.register("Alice", email="alice@example.com")
# client now has api_key set

# Option B: create workspace
# data = client.create_workspace("demo")
# client.set_api_key(data["api_key"])

client.store_memory(
    workspace_id=data["workspace_id"],
    content="Found the artifact in sector 7",
    scope="private",
    tags=["artifact"],
)
# optional: agent_id="cursor" to record which tool created it
results = client.query_memories(
    workspace_id=data["workspace_id"],
    query="artifact",
)
print(results)
client.close()

MCP (Cursor)

Set RECALL_API_BASE_URL and RECALL_API_KEY (e.g. from register or workspace creation), then point Cursor at the Recall MCP server. Tools: recall_search_memories, recall_store_memory, recall_get_memory, recall_smart_search, recall_list_workspaces, recall_list_agents, recall_create_agent.

Layout

• api/ — FastAPI app, routes, services, models
• sdk/ — Python client
• mcp_server/ — MCP tools for Cursor