This project has been archived by its maintainers, and is no longer receiving any updates.
z3rno-server
⚠️ Deprecated — full rewrite in progress
z3rno is being rewritten from the ground up as a single open-source Rust monorepo (Apache 2.0), following direct feedback from enterprise users that the current architecture is too complex.
- Maintenance mode only — bug fixes, no new features.
- Existing installs keep working. Nothing here is being yanked, archived, or removed.
- The new monorepo lands at
the-ai-project-co/z3rno.- Track progress: https://github.com/the-ai-project-co/z3rno-server/issues/3
FastAPI REST API server for Z3rno -- wraps z3rno-core engine functions as HTTP endpoints.
Quickstart
Run with Docker Compose
cp .env.example .env # configure DATABASE_URL, API keys, etc.
docker compose -f docker-compose.dev.yml up
This starts PostgreSQL 17 (with pgvector, Apache AGE), Valkey, the API server on localhost:8000, and a Celery worker.
Store a memory
curl -X POST http://localhost:8000/v1/memories \
-H "Authorization: Bearer z3rno_sk_test_localdev" \
-H "Content-Type: application/json" \
-d '{"agent_id": "agent-1", "content": "User prefers dark mode", "memory_type": "semantic"}'
Recall memories
curl -X POST http://localhost:8000/v1/memories/recall \
-H "Authorization: Bearer z3rno_sk_test_localdev" \
-H "Content-Type: application/json" \
-d '{"agent_id": "agent-1", "query": "What does the user prefer?", "top_k": 5}'
Forget a memory
curl -X POST http://localhost:8000/v1/memories/forget \
-H "Authorization: Bearer z3rno_sk_test_localdev" \
-H "Content-Type: application/json" \
-d '{"memory_id": "<memory-uuid>"}'
For a detailed step-by-step setup, see QUICKSTART.md.
Full documentation: astron-bb4261fd.mintlify.app
API Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /v1/memories |
Store a new memory |
| POST | /v1/memories/recall |
Recall memories by semantic query |
| POST | /v1/memories/forget |
Soft-delete a memory |
| GET | /v1/audit |
Query the audit log |
| POST | /v1/sessions |
Start a new session |
| POST | /v1/sessions/{id}/end |
End a session |
| GET | /v1/sessions/{id} |
Get session state |
| GET | /v1/health |
Health check |
| GET | /v1/ready |
Readiness check |
Configuration
All configuration is via environment variables:
| Variable | Description | Default |
|---|---|---|
DATABASE_URL |
PostgreSQL connection string (asyncpg) | required |
VALKEY_URL |
Valkey URL (falls back to REDIS_URL) |
redis://localhost:6379/0 |
Z3RNO_API_KEY |
API key for authentication | required |
EMBEDDING_MODEL |
LiteLLM embedding model name | text-embedding-3-small |
OPENAI_API_KEY |
OpenAI API key (for embeddings) | -- |
LOG_LEVEL |
Logging level | INFO |
CORS_ORIGINS |
Allowed CORS origins (comma-separated) | -- |
OpenAPI Documentation
When running locally, interactive API docs are available at:
- Swagger UI:
http://localhost:8000/docs - ReDoc:
http://localhost:8000/redoc
Development
uv sync --dev
uv run ruff check .
uv run mypy .
uv run pytest
See CONTRIBUTING.md for the full workflow.
License
Apache 2.0 -- see LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for z3rno-server 0.22.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| z3rno_server-0.22.3.tar.gz | 454.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| z3rno_server-0.22.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 572.1 kB
Release files / z3rno_server-0.22.3.tar.gz
| Download URL | z3rno_server-0.22.3.tar.gz |
|---|---|
| Size | 454.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5c09ab30ca7c501b637992427345c262d4d6ade134f8fe1ead3b39834803b88e
|
|
BLAKE2b-256 checksum How to use checksums |
75e2e38a4ad2178f3b60477a26a6cb8aeb4cfb2de5c6518e813d8ef2d0e4ed73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / z3rno_server-0.22.3-py3-none-any.whl
| Download URL | z3rno_server-0.22.3-py3-none-any.whl |
|---|---|
| Size | 117.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7a0a9b0939739a0a250950c16b8658a2aeb52b0480545b41d832092cc7a7eafc
|
|
BLAKE2b-256 checksum How to use checksums |
4a4bdcb15873bcf844b29c2e4026483d5f41b3c05df831c9ae8dd161ae0ec0b8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
