imprint-server 0.2.1

Networked memory service for AI agents, built on imprint-mem.

imprint-server

Networked memory service for AI agents, built on imprint-mem.

Exposes the full imprint-mem API over HTTP/REST and MCP SSE. Supports SQLite for local development and Postgres for production multi-worker deployments.

Install

pip install imprint-server

Quick start

# SQLite (local, zero infrastructure)
imprint-server serve

# Postgres (production)
IMPRINT_STORE=postgres://user:pass@host/db \
IMPRINT_AUTH_DISABLED=false \
imprint-server serve

On first start with auth enabled and an empty key store, the server generates and prints a master API key. Copy it -- it is not stored.

Docker

# Start Postgres + imprint-server via Docker Compose
docker compose -f imprint-server/docker-compose.yml up

# Or build and run the image directly
docker build -t imprint-server -f imprint-server/Dockerfile .
docker run -p 8000:8000 imprint-server

MCP (Claude Code, Cursor, Continue)

Set two environment variables before starting:

IMPRINT_MCP_AGENT_ID=my-agent \
IMPRINT_MCP_USER_ID=my-user \
imprint-server serve

Then add http://localhost:8000/mcp/sse as an MCP server in your client. Eight tools are available: imprint_begin_session, imprint_get_policy, imprint_observe, imprint_recall, imprint_direct, imprint_end_session, imprint_correct, imprint_reinforce.

Python client

from imprint.client import ImprintClient

# Requires: pip install imprint-mem[client]

async with ImprintClient("http://localhost:8000", api_key="sk-imp-...") as client:
    # Compile a behavioral policy for a user.
    policy = await client.get_policy("my-agent", "user-1")
    print(policy.text)

    # Record a turn.
    await client.observe("my-agent", "user-1",
        agent_output="Here is a bullet list.",
        user_response="No bullet points please.")

    # Search memories semantically (falls back to list order without embedder):
    memories = await client.search_memories("my-agent", "user-1", "formatting style")

    # Store a correction and apply a negative learning signal:
    await client.correct("my-agent", "user-1", "No bullet points please.")

    # Pin a memory so it is never dropped by token budget truncation:
    await client.pin_memory("my-agent", memories[0].id)

    # Soft-deactivate a single memory (reversible, unlike forget()):
    await client.deactivate_memory("my-agent", "user-1", memories[0].id)

    # Session-scoped usage (enables learning signal on close):
    async with client.session("my-agent", "user-1", context="coding") as sess:
        policy = await sess.get_policy()
        await sess.observe("output", "response")
        sess.set_outcome(0.9)

    # Or apply a positive signal directly after a session:
    sess_id = await client.open_session("my-agent", "user-1")
    await client.reinforce("my-agent", "user-1", session_id=sess_id)

# Agent-scoped shortcut (avoids repeating agent_id):
agent = client.agent("my-agent")
policy = await agent.get_policy("user-1")

CLI

imprint-server serve             # start the HTTP server
imprint-server migrate           # run schema migrations only (no server)
imprint-server keys create       # generate a new API key
imprint-server keys list         # list all keys (hashes + labels)
imprint-server keys revoke HASH  # revoke a key by its SHA-256 hash

REST API

POST   /v1/agents/{agent_id}/observe
POST   /v1/agents/{agent_id}/policy
GET    /v1/agents/{agent_id}/memories/{user_id}
GET    /v1/agents/{agent_id}/memories/{user_id}/search
DELETE /v1/agents/{agent_id}/memories/{user_id}
DELETE /v1/agents/{agent_id}/memories/{user_id}/{memory_id}
POST   /v1/agents/{agent_id}/memories/{memory_id}/pin
POST   /v1/agents/{agent_id}/memories/{user_id}/consolidate
POST   /v1/agents/{agent_id}/memories/{user_id}/directions
POST   /v1/agents/{agent_id}/correct/{user_id}
POST   /v1/agents/{agent_id}/reinforce/{user_id}
GET    /v1/agents/{agent_id}/events/{user_id}
GET    /v1/agents/{agent_id}/health/{user_id}
GET    /v1/memories/{memory_id}/lineage

POST   /v1/agents/{agent_id}/sessions
POST   /v1/agents/{agent_id}/sessions/{id}/observe
POST   /v1/agents/{agent_id}/sessions/{id}/policy
POST   /v1/agents/{agent_id}/sessions/{id}/close

GET    /v1/agents
POST   /v1/agents
GET    /v1/agents/{agent_id}
PATCH  /v1/agents/{agent_id}/config
DELETE /v1/agents/{agent_id}
POST   /v1/agents/{agent_id}/scopes/consolidate

GET    /health
GET    /metrics
GET    /mcp/sse

Configuration

All settings via environment variables (prefix IMPRINT_). See .env.example for the full list with defaults and comments.

Key settings:

Variable	Default	Description
IMPRINT_STORE	sqlite:///~/.imprint/imprint.db	SQLite path or Postgres URL
IMPRINT_AUTH_DISABLED	true	Set false to require API keys
IMPRINT_DEFAULT_MODE	balanced	frugal, balanced, or eager
IMPRINT_EMBEDDER	none	none, voyage, or openai
IMPRINT_EMBEDDER_MODEL	voyage-3	Model string for the chosen embedder
IMPRINT_EMBEDDER_DIM	1024	Output dimension (must match vector store)
IMPRINT_VECTOR_STORE	none	none, sqlite-vec, or postgres
IMPRINT_DECAY_MODEL	static	static or gradient (requires [online])
IMPRINT_MCP_AGENT_ID	``	Agent ID for the MCP endpoint
IMPRINT_MCP_USER_ID	``	User namespace for the MCP endpoint
IMPRINT_PORT	8000	Bind port
IMPRINT_WORKERS	1	Uvicorn worker count (Postgres only for >1)

Development

Requires uv and just.

just server-dev                   # serve with SQLite, auth disabled
just server-mcp-dev               # serve with MCP enabled
just server-check                 # lint, typecheck, test
just server-live-test             # live retrieval tests (requires VOYAGE_API_KEY)
just server-integration-test      # Postgres tests via Docker Compose
just test-all                     # full suite: library + server + Postgres
just live-all                     # all live tests across library + server (requires API keys)