Clark

Clark is a memory layer for personal agents. It stores profile, factual, episodic, and procedural memory behind one query surface, so tools such as Hermes, Codex, Claude Code, Gemini CLI, Cursor, and MCP-compatible agents can retrieve useful context without stitching several memory systems together.

The repository is being hardened for open-source production use. The current production path is:

• Postgres 16 with pgvector for server deployments.
• SQLite plus sqlite-vec for local development and single-user experiments.
• DeepSeek for LLM extraction by default.
• Gemini embeddings by default.
• FastAPI HTTP API with bearer-token auth.
• MCP server for agent-native integration.
• uv for local development and CI-style commands.

Status

Clark is ready for public open-source development and production-path evaluation. The local CLI, HTTP API, MCP transports, Docker path, Postgres/pgvector backend, and provider contracts are covered by real tests.

Benchmark claims are intentionally conservative: publish comparative numbers only when they come from the checked-in benchmark runners, real provider credentials, and recorded artifacts.

Install

git clone https://github.com/Nomads-AI-Lab/clark.git
cd clark
uv sync --extra test --extra server --extra mcp --extra postgres

For local editable development:

uv pip install -e ".[test,server,mcp,postgres]"

Configuration

Create .env from .env.example and set real credentials:

cp .env.example .env

Required for production server mode:

CLARK_ENV=production
CLARK_AUTH_TOKEN=replace-with-a-long-random-token
CLARK_DATABASE_URL=postgresql://clark:strong-password@postgres:5432/clark
GEMINI_API_KEY=...
DEEPSEEK_API_KEY=...

Important behavior:

• Clark does not silently replace missing providers with fake embeddings or fake LLM output.
• If a required provider key is absent for the code path you run, the operation fails explicitly.
• Server production mode requires CLARK_AUTH_TOKEN.

CLI

uv run clark doctor
uv run clark migrate
uv run clark stats
uv run clark remember "Alice prefers concise technical answers"
uv run clark query "How should I answer Alice?"
uv run clark session-start

clark migrate applies the Postgres/pgvector schema when CLARK_DATABASE_URL is set. Without CLARK_DATABASE_URL, the legacy SQLite schema initializes on first use.

Docker

cp .env.example .env
# edit .env and set strong real values
docker compose up --build

Then migrate the database:

docker compose exec clark-api clark migrate

Health and API smoke:

curl http://127.0.0.1:8000/healthz
curl -H "Authorization: Bearer $CLARK_AUTH_TOKEN" http://127.0.0.1:8000/v1/stats

HTTP API

uv run clark serve 8000

Endpoints:

• GET /healthz
• GET /readyz
• GET /v1/stats
• POST /v1/memories
• POST /v1/query

Authenticated request:

curl -X POST http://127.0.0.1:8000/v1/memories \
  -H "Authorization: Bearer $CLARK_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Alice is building a production memory layer","source":"api"}'

MCP

Run a stdio MCP server:

uv run clark mcp

Run streamable HTTP transport:

uv run clark mcp streamable-http

Available tools:

• clark_health
• clark_stats
• clark_query
• clark_remember

Resource:

• clark://stats

When CLARK_DATABASE_URL is set, MCP uses the Postgres backend. Otherwise it uses the local SQLite backend.

Python API

from clark import HybridMemory

memory = HybridMemory()
memory.remember("Alice works on agent memory infrastructure")
result = memory.query("What does Alice work on?")
print(result["results"])

For production server deployments, prefer the HTTP API or MCP server over importing the legacy SQLite class directly.

Tests

Run the local suite:

uv run pytest

Run real provider contract tests:

GEMINI_API_KEY=... DEEPSEEK_API_KEY=... uv run pytest tests/test_provider_contracts.py

Run real Postgres/pgvector integration tests:

docker run --rm -d --name clark-pgvector-test \
  -p 15434:5432 \
  -e POSTGRES_DB=clark \
  -e POSTGRES_USER=clark \
  -e POSTGRES_PASSWORD=clark-local-dev-password \
  pgvector/pgvector:pg16

CLARK_DATABASE_URL=postgresql://clark:clark-local-dev-password@127.0.0.1:15434/clark \
GEMINI_API_KEY=... \
uv run pytest tests/test_postgres_backend.py

docker rm -f clark-pgvector-test

Open-Source Documents

• Production readiness roadmap
• Agent integrations
• Benchmark methodology
• Verification status
• Contributing guide
• Security policy
• Code of conduct
• MIT License

Security

Do not expose the HTTP API without CLARK_AUTH_TOKEN. Do not commit .env, database dumps, provider keys, or personal memory exports. Treat memory contents as sensitive user data.