MIT · Free Forever

Zikra Lite

This is where Zikra started — Mukarram's first build to fix the Claude Web ↔ Claude Code disconnect. One Python process. One SQLite file. No Docker, no PostgreSQL. If you're a solo developer, this is all you need.

Python 3.11+ FastAPI SQLite sqlite-vec httpx uvicorn

Up in 60 seconds

Three commands and your agent has persistent memory.

# Install $ pip install zikra-lite # Configure — set OPENAI_API_KEY and ZIKRA_TOKEN $ cp .env.example .env && nano .env # Start the server $ python -m zikra Zikra Lite running at http://localhost:7723/webhook/zikra

Or clone from github.com/getzikra/zikra-lite and run pip install -r requirements.txt

Every command available

All sent as POST /webhook/zikra with a Bearer token.

🔍

search

Hybrid vector + keyword search across all memories. Returns ranked results with scores and snippets. Token budget applied automatically.

aliases: find · query · recall · retrieve

💾

save_memory

Save any context — decisions, patterns, errors — with an embedding. Deduplicates by title + type. Access count tracked per memory.

aliases: save · store · write

📖

get_memory

Retrieve a specific memory by title or ID. Returns full content, tags, resolution, and timestamps.

aliases: fetch_memory · read_memory

📋

get_prompt

Retrieve a named runbook prompt by title. Increments access count. Use to store and retrieve reusable agent instructions.

aliases: fetch_prompt · run_prompt

📝

log_run

Log a completed agent session with status, token counts, cost, and a summary. Builds an audit trail of AI activity.

aliases: log_session · end_session

🐛

log_error

Log errors and failures with type, message, stack trace, and context. Query later to spot recurring patterns.

aliases: log_bug · report_error

📌

save_requirement

Save a project requirement with searchable content. Stored as a memory with type requirement — searchable alongside all other context.

🗃️

get_schema

Return the full SQLite schema — all table definitions. Useful for debugging and confirming Lite is running correctly.

aliases: schema

Command Aliases Required fields Description
search find, query, recall, retrieve, remember query Hybrid search. Optional: limit (default 5), max_tokens (default 2000), project
save_memory save, store, write, add_memory title Save memory. Optional: content_md, memory_type, tags, project, module, created_by
get_memory fetch_memory, read_memory, load_memory title or id Get a single memory by title or ID. Optional: memory_type for disambiguation
get_prompt fetch_prompt, run_prompt, load_prompt prompt_name Get a named prompt (memory_type='prompt'). Increments access_count
log_run log_session, end_session, finish_run Log a run. Optional: project, runner, status, output_summary, tokens_input, tokens_output, cost_usd
log_error log_bug, report_error, save_error message Log an error. Optional: project, runner, error_type, stack_trace, context_md
save_requirement title Save a requirement (stored as memory_type='requirement'). Optional: content_md, project, tags
get_schema schema Return SQLite table schema. No required fields

Configuration

Two required variables. Everything else has sane defaults.

Variable Required Default Description
OPENAI_API_KEY yes OpenAI key for text-embedding-3-small. Swap OPENAI_API_BASE for local models.
ZIKRA_TOKEN yes Bearer token — all requests must include Authorization: Bearer <token>
ZIKRA_PORT no 7723 HTTP port for the FastAPI server
ZIKRA_DB_PATH no ./zikra.db Path to the SQLite database file
OPENAI_API_BASE no https://api.openai.com/v1 Swap for a local Ollama or compatible embedding endpoint
ZIKRA_EMBEDDING_MODEL no text-embedding-3-small Embedding model name — must produce 1536-dim vectors

100% open source. MIT licensed.

Fork it, embed it, ship it. No attribution required beyond the license header. Star the repo if Zikra Lite saves you time.