Zikra MCP server

Zikra — Team Memory for AI Agents

Not just session memory. A shared, governed memory layer for every agent, every person, and every project your team runs.

Website: zikra.dev · Self-hosted · MIT · Scales to millions of memories

Architecture: Governed project memory for teams of agents

Promotion kit: submission copy, launch posts, and directory targets

zikra 17 runs · 847 memories │ you@team-server │ Sonnet 4.6 │ ~/project (main) │ 387K/200K ████░░░░░░ 45%

---

Install in one line

claude mcp add zikra http://localhost:8000/mcp --header "Authorization: Bearer YOUR_TOKEN"

Or add to ~/.claude/settings.json:

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

Don't have a server yet? → Step 1 below takes ~2 minutes.

---

Most AI memory tools solve one problem: one agent remembers one session better.

Zikra solves a harder problem: multiple people running multiple AI agents across multiple projects — all sharing the same memory pool, with the right person scoped to the right project, the right agent pulling the right context, and millions of memories staying fresh through built-in hygiene scoring.

It's not session memory. It's the shared brain for an AI-native team.

What you get	What that means
Multi-agent	Claude Code, Gemini CLI, Codex — one pool, one token
Multi-person	Owner / admin / dev / viewer roles per project
Multi-project	Isolated namespaces; one team runs veltisai, design, global
Scale	PostgreSQL backend — handles millions of memories without index rebuilds
Memory hygiene	Built-in hygiene prompt: confidence decay, orphan detection, stale cleanup
Structure	Not just "save text" — decisions, requirements, prompts, errors, session diaries
Auto-save	Stop + PreCompact hooks write every session automatically

— Mukarram

---

How Zikra compares

	Zikra	MCP Memory¹	mem0	basic-memory	MemoryMesh
Works across multiple AI tools	✅	❌	✅ paid	❌	❌
Team sharing with per-user roles	✅ RBAC	❌	✅ paid	❌	❌
Multi-project namespacing	✅	❌	✅ paid	❌	❌
Self-hosted, zero cloud dependency	✅	✅	❌	✅	✅
Auto-save via session hooks	✅	❌	❌	❌	❌
Hybrid vector + keyword search	✅	❌ graph only	✅	❌	❌
Confidence decay / memory hygiene	✅ built-in prompt	❌	❌	❌	❌
Named prompts + requirements	✅	❌	❌	❌	❌
Scales to millions of memories	✅ Postgres	❌ in-memory	✅ cloud	❌	❌
License	MIT	MIT	Proprietary	MIT	MIT

¹ @modelcontextprotocol/server-memory — the official Anthropic reference server.

---

Getting Started

Step 1 — Install the server

git clone https://github.com/getzikra/zikra
cd zikra
python3 -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e .
python3 installer.py         # interactive setup, ~2 minutes
python3 -m zikra

The installer creates a .env file and generates your admin token. The server binds to http://localhost:8000 by default.

To reach it from other machines, run cloudflared tunnel --url http://localhost:8000 (free, gives you a permanent public URL like https://zikra.yourteam.com).

Step 2 — Enable MCP in Claude Code

Open Claude Code → Settings → MCP → Add Server and paste:

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

The installer does this automatically when run locally.

Step 3 — Connect your AI coding agent

Paste the prompt for your agent into a session. It handles both first install and updates.

Claude Code:

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

This installs the Stop hook (auto-saves every session), PreCompact hook, and the live statusline bar showing run counts and memory stats.

---

Updating Zikra

Server:

cd ~/zikra && ./update.sh

Claude Code hooks — re-run the onboarding prompt. It detects your existing install and only refreshes what changed.

---

Profiles

Profile	Storage	Hooks	Extra deps
Webhook (default)	SQLite ¹	none	none
Auto-log	SQLite ¹	session hooks	none
Full	SQLite ¹ or Postgres	hooks + daemon	asyncpg (Postgres only)

¹ SQLite is for local / single-user only. For team deployments set DB_BACKEND=postgres.

---

Environment variables

Variable	Required	Default	Description
ZIKRA_TOKEN	Yes	generated	Bearer token for the API
OPENAI_API_KEY	No	—	Enables semantic search. Keyword-only if absent.
DB_BACKEND	No	sqlite	sqlite or postgres
DB_HOST	Postgres only	localhost
DB_PORT	Postgres only	5432
DB_NAME	Postgres only	—
DB_USER	Postgres only	—
DB_PASSWORD	Postgres only	—
ZIKRA_HOST	No	0.0.0.0	Bind address
ZIKRA_PORT	No	8000	HTTP port
ZIKRA_DB_PATH	No	./zikra.db	SQLite database path
ZIKRA_PROJECT	No	main	Default project
OPENAI_API_BASE	No	https://api.openai.com/v1	Swap for local or compatible embedding endpoint
ZIKRA_EMBEDDING_MODEL	No	text-embedding-3-small	Embedding model name
ZIKRA_DECAY_DAYS	No	30	Memory half-life in days
ZIKRA_FREQUENCY_WEIGHT	No	0.1	Access-frequency boost weight

---

How results are ranked

Every search result passes through scoring:

• Age — recent memories rank higher. Half-life: 30 days. Floor: 0.05.
• Access frequency — frequently used prompts surface higher (log scale).
• Confidence — memories saved with lower confidence_score rank lower.

---

Command reference

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

Command	Aliases	Description
search	find, query, recall	Hybrid semantic + keyword search
save_memory	save, store	Save a memory with embedding
get_memory	fetch_memory	Retrieve by title or id
get_prompt	fetch_prompt	Retrieve a named prompt
log_run	log_session	Log a completed agent run
log_error	log_bug	Log an error
save_requirement	—	Save a project requirement
save_prompt	write_prompt	Save a prompt with embedding
list_prompts	get_prompts	List prompts for a project
list_requirements	list_reqs	List requirements
promote_requirement	promote	Change a requirement's type
create_token	new_token	Generate a bearer token (owner role)
get_schema	schema	DB DDL introspection
zikra_help	help	Full command reference
debug_protocol	—	Backend diagnostics

Roles: owner · admin · developer · viewer

---

PostgreSQL backend

DB_BACKEND=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ai_zikra
DB_USER=postgres
DB_PASSWORD=yourpassword

pip install -e ".[postgres]"

---

License

MIT — see LICENSE

Design in Claude Web. Execute in Claude Code. Share with your whole team. Claude Web · Claude Code · Gemini CLI · Codex · any agent that can POST.