zikra-lite

Zero-dependency persistent memory for AI agents. FastAPI + SQLite + sqlite-vec.

Self-hosted · Single-process · No Docker · No PostgreSQL · No n8n

pip install zikra-lite

---

This is where Zikra started. I was doing architecture on Claude Web and running code on Claude Code — two tools with no shared context. Built this to bridge the gap. One Python process, one SQLite file, nothing else to install. It fixed the problem in under a minute.

If your team has grown and you need shared memory across machines, see Zikra (PostgreSQL + n8n). Same API — upgrade is just changing a URL.

— Mukarram

---

Quick start

pip install zikra-lite
cp .env.example .env   # set OPENAI_API_KEY and ZIKRA_TOKEN
python -m zikra        # starts server on port 7723

Or run from source:

git clone https://github.com/getzikra/zikra-lite
cd zikra-lite
pip install -r requirements.txt
cp .env.example .env
python -m zikra

---

Web UI

Zikra Lite includes a web interface to browse memories, view prompt runs, manage tokens, and search across your project.

To start the UI:

cd ui
npm install
npm run dev

Open http://localhost:5173 in your browser.

The UI reads your token and URL from ui/.env — copy ui/.env.example and fill in your values.

---

Environment variables

Variable	Required	Default	Description
OPENAI_API_KEY	yes	—	OpenAI key for embeddings
ZIKRA_TOKEN	yes	—	Bearer token for API auth
ZIKRA_PORT	no	7723	HTTP port
ZIKRA_DB_PATH	no	./zikra.db	SQLite database path
OPENAI_API_BASE	no	https://api.openai.com/v1	Swap for local model
ZIKRA_EMBEDDING_MODEL	no	text-embedding-3-small	Embedding model name

---

Command reference

All commands are sent as POST /webhook/zikra with Authorization: Bearer <token>.

Command	Aliases	Description
search	find, query, recall, retrieve	Hybrid semantic + keyword search
save_memory	save, store, write	Save a memory with embedding
get_memory	fetch_memory, read_memory	Retrieve memory by title or id
get_prompt	fetch_prompt, run_prompt	Retrieve a named prompt
log_run	log_session, end_session	Log a completed agent run
log_error	log_bug, report_error	Log an error or failure
save_requirement	—	Save a project requirement
get_schema	schema	Return the database schema

Example request

POST /webhook/zikra
Authorization: Bearer your-secret-token

{
  "command": "search",
  "project": "myapp",
  "query": "how does authentication work",
  "limit": 5
}

---

Run tests

OPENAI_API_KEY=sk-... python -m zikra.tests.test_all

19 tests covering all commands, aliases, auth, token budgeting, and semantic search.

---

Upgrading to Zikra

When your team joins, Lite has two limits: SQLite concurrent writes and no multi-machine sync. Zikra (PostgreSQL + pgvector + n8n) removes both. Same API surface — upgrade path is zero friction.

Feature	Lite	Zikra
Concurrent writes	Limited	Unlimited
Multi-machine sync	❌	✅
n8n workflows	❌	✅
Scale	Millions of rows	Billions of rows
Setup time	60 seconds	30–60 minutes

See github.com/getzikra/zikra.

---

Sharing Zikra with your team

By default Zikra runs on your machine at localhost:7723. To share it with teammates you just need a permanent address they can connect to. Pick the option that fits:

Same office or home network — nothing to install

Start Zikra and share your local IP. That is it.

python -m zikra --host 0.0.0.0
hostname -I

Teammates connect to http://YOUR-IP:7723 and they are in. Works as long as everyone is on the same wifi or office network.

Remote teammates — Cloudflare Tunnel

One time setup. Takes about 5 minutes. Free forever.

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared && sudo mv cloudflared /usr/local/bin
cloudflared tunnel login
cloudflared tunnel create zikra
cloudflared tunnel route dns zikra zikra.yourteam.com

After that your Zikra is permanently live at https://zikra.yourteam.com — no commands to run each time, no ports to open, no router config. Cloudflare handles it.

Not ready to self host? — Zikra Full

If you want someone else to run the server, Zikra Full runs on your own VPS with Docker. One docker compose up and it runs forever in the background. Same commands, same Claude Code config, just a real server instead of your laptop.

---

License

MIT — see LICENSE