How to Install Zikra — 3 Steps to Persistent AI Memory

1

Install the server

Clone the repo and run the interactive installer. Zikra is a single Python process — no Docker, no database setup, no config files to hand-write. The installer generates your admin token and writes a .env file automatically.

                        $ git clone https://github.com/GetZikra/zikra
                        $ cd zikra && pip install -e .
                        $ python3 installer.py
                        $ python3 -m zikra
                        ✓  Zikra running on http://localhost:8000
                    

Expose to other machines — run Cloudflare Tunnel for a free, permanent public URL:

                            $ cloudflared tunnel --url http://localhost:8000
                            ✓  https://zikra.yourteam.com
                        

2

Enable MCP in Claude Code

Open Claude Code → Settings → MCP → Add Server and paste your server's endpoint. This gives Claude Code native access to Zikra tools — search, save, and recall memory directly from any conversation.

                        "mcpServers": {
                        "zikra": {
                        "url": "http://your-server:8000/mcp",
                        "headers": {"Authorization": "Bearer YOUR_TOKEN"}
                        }
                        }
                    

Replace your-server:8000 with localhost:8000 for a local install, or your Cloudflare Tunnel URL for remote access. The installer writes this automatically for local installs — you can skip this step if you ran it on the same machine.

3

Connect your AI coding agent

Paste the prompt for your agent into a session. Handles both first install and updates — run the same prompt any time to install or refresh.

Claude Code

                        Fetch https://raw.githubusercontent.com/GetZikra/zikra/main/prompts/zikra-claude-code-setup.md
                        and follow every instruction in it.
                    

Gemini CLI

Re-run the installer and choose Gemini CLI when asked "Other AI tools to integrate with?". The installer writes hook entries into ~/.gemini/settings.json automatically.

                        # If you already ran the installer, re-run it:
                        $ python3 installer.py
                          Other AI tools to integrate with?
                          [2] Gemini CLI  (detected)
                    

Hooks fire on AfterModel and SessionEnd. Token counts are parsed from the Gemini JSONL transcript. The same statusline bar you see in Claude Code appears before each terminal prompt.

Codex CLI

Same installer step — choose Codex CLI or Both. Writes hook entries into ~/.codex/config.toml (or hooks.json on newer Codex versions).

                        # Re-run installer and pick Codex or Both:
                        $ python3 installer.py
                          Other AI tools to integrate with?
                          [3] Codex CLI   (detected)
                          [4] Both Gemini and Codex
                    

Hooks fire on Stop and PostToolUse. Token counts are parsed from history.jsonl. Shell statusline sourced into your RC file automatically.

Claude Code will ask for your server URL and token, then install:

🪝

Stop hook

Auto-saves a memory at the end of every Claude Code session. You never have to type "save this".

⚡

PreCompact hook

Saves context before Claude compacts long conversations, so nothing is lost when the context window fills.

📊

Statusline bar

Live bar below the input showing run counts, memory count, and context usage.

What happens from here

Once the onboarding prompt finishes, memory is live from the first message of every new session.

💾

Every session is saved

When you end a Claude Code session, the Stop hook fires automatically and saves a summary to Zikra. No manual action needed.

🔍

Memory is searchable

Ask Claude "what did we decide about auth?" and it searches Zikra automatically using hybrid vector + keyword search.

🌐

Works across machines

Run the same onboarding prompt on any machine. Every machine connects to the same memory pool — one server, every device.

Keeping Zikra updated

Server and Claude Code hooks update independently. Both are one command.

Update the server

Pull latest and restart. Your .env and database are untouched.

                    $ git pull origin main
                    $ pip install -e .
                    $ python3 -m zikra
                

Update hooks (all tools)

Claude Code — re-run the onboarding prompt. Detects your existing install, refreshes only what changed, preserves token and config.

                    Fetch https://raw.githubusercontent.com/
                    GetZikra/zikra/main/prompts/zikra-claude-code-setup.md
                    and follow every instruction in it.
                

Gemini CLI / Codex CLI — re-run the installer. Hook scripts are replaced in-place; tool configs are updated non-destructively.

                    $ git pull origin main
                    $ python3 installer.py
                

MCP server settings never need manual updates.

Get started in 3 steps