{"id":51223050,"url":"https://github.com/getzikra/Zikra","last_synced_at":"2026-07-16T19:01:03.584Z","repository":{"id":348609307,"uuid":"1195682219","full_name":"getzikra/Zikra","owner":"getzikra","description":"Persistent memory MCP server for Claude Code — self-hosted, n8n + PostgreSQL + pgvector. No cloud required.","archived":false,"fork":false,"pushed_at":"2026-06-27T03:56:42.000Z","size":756,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T05:16:04.512Z","etag":null,"topics":["agent-memory","ai-agents","ai-memory","anthropic","claude-code","claude-code-mcp","claude-code-plugin","claude-memory","developer-tools","knowledge-management","llm-memory","mcp","mcp-server","model-context-protocol","n8n","persistent-memory","pgvector","postgresql","python","self-hosted"],"latest_commit_sha":null,"homepage":"https://zikra.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getzikra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-30T00:39:01.000Z","updated_at":"2026-06-27T03:56:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/getzikra/Zikra","commit_stats":null,"previous_names":["getzikra/zikra"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/getzikra/Zikra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getzikra%2FZikra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getzikra%2FZikra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getzikra%2FZikra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getzikra%2FZikra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getzikra","download_url":"https://codeload.github.com/getzikra/Zikra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getzikra%2FZikra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35555509,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","ai-memory","anthropic","claude-code","claude-code-mcp","claude-code-plugin","claude-memory","developer-tools","knowledge-management","llm-memory","mcp","mcp-server","model-context-protocol","n8n","persistent-memory","pgvector","postgresql","python","self-hosted"],"created_at":"2026-06-28T09:00:31.116Z","updated_at":"2026-07-16T19:01:03.574Z","avatar_url":"https://github.com/getzikra.png","language":"Python","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"# Zikra — Team Memory for AI Agents\n\n\u003e Not just session memory. A shared, governed memory layer for every agent, every person, and every project your team runs.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-native-blue)](https://modelcontextprotocol.io/)\n[![MCP Server](https://glama.ai/mcp/servers/getzikra/zikra/badges/score.svg)](https://glama.ai/mcp/servers/getzikra/zikra)\n\n**Website:** [zikra.dev](https://zikra.dev) · Self-hosted · MIT · Scales to millions of memories\n\n**Architecture:** [Governed project memory for teams of agents](docs/architecture.md)\n\n**Promotion kit:** [submission copy, launch posts, and directory targets](PROMOTION.md)\n\n```\nzikra 17 runs · 847 memories │ you@team-server │ Sonnet 4.6 │ ~/project (main) │ 387K/200K ████░░░░░░ 45%\n```\n\n---\n\n## Install in one line\n\n```bash\nclaude mcp add zikra http://localhost:8000/mcp --header \"Authorization: Bearer YOUR_TOKEN\"\n```\n\nOr add to `~/.claude/settings.json`:\n\n```json\n{ \"mcpServers\": { \"zikra\": { \"url\": \"http://localhost:8000/mcp\", \"headers\": { \"Authorization\": \"Bearer YOUR_TOKEN\" } } } }\n```\n\n**Don't have a server yet?** → [Step 1 below](#step-1--install-the-server) takes ~2 minutes.\n\n---\n\nMost AI memory tools solve one problem: one agent remembers one session better.\n\nZikra 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.\n\nIt's not session memory. It's the shared brain for an AI-native team.\n\n| What you get | What that means |\n|---|---|\n| **Multi-agent** | Claude Code, Gemini CLI, Codex — one pool, one token | \n| **Multi-person** | Owner / admin / dev / viewer roles per project |\n| **Multi-project** | Isolated namespaces; one team runs `veltisai`, `design`, `global` |\n| **Scale** | PostgreSQL backend — handles millions of memories without index rebuilds |\n| **Memory hygiene** | Built-in hygiene prompt: confidence decay, orphan detection, stale cleanup |\n| **Structure** | Not just \"save text\" — decisions, requirements, prompts, errors, session diaries |\n| **Auto-save** | Stop + PreCompact hooks write every session automatically |\n\n— Mukarram\n\n---\n\n## How Zikra compares\n\n| | **Zikra** | MCP Memory¹ | mem0 | basic-memory | MemoryMesh |\n|---|---|---|---|---|---|\n| Works across **multiple AI tools** | ✅ | ❌ | ✅ paid | ❌ | ❌ |\n| **Team sharing** with per-user roles | ✅ RBAC | ❌ | ✅ paid | ❌ | ❌ |\n| **Multi-project** namespacing | ✅ | ❌ | ✅ paid | ❌ | ❌ |\n| Self-hosted, zero cloud dependency | ✅ | ✅ | ❌ | ✅ | ✅ |\n| Auto-save via session hooks | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Hybrid vector + keyword search | ✅ | ❌ graph only | ✅ | ❌ | ❌ |\n| Confidence decay / memory hygiene | ✅ built-in prompt | ❌ | ❌ | ❌ | ❌ |\n| Named prompts + requirements | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Scales to millions of memories | ✅ Postgres | ❌ in-memory | ✅ cloud | ❌ | ❌ |\n| License | MIT | MIT | Proprietary | MIT | MIT |\n\n¹ `@modelcontextprotocol/server-memory` — the official Anthropic reference server.\n\n---\n\n## Getting Started\n\n### Step 1 — Install the server\n\n```bash\ngit clone https://github.com/getzikra/zikra\ncd zikra\npython3 -m venv .venv\nsource .venv/bin/activate    # Windows: .venv\\Scripts\\activate\npip install -e .\npython3 installer.py         # interactive setup, ~2 minutes\npython3 -m zikra\n```\n\nThe installer creates a `.env` file and generates your admin token. The server binds to `http://localhost:8000` by default.\n\n\u003e 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`).\n\n### Step 2 — Enable MCP in Claude Code\n\nOpen **Claude Code → Settings → MCP → Add Server** and paste:\n\n```json\n{\n  \"mcpServers\": {\n    \"zikra\": {\n      \"url\": \"http://your-server:8000/mcp\",\n      \"headers\": { \"Authorization\": \"Bearer YOUR_ZIKRA_TOKEN\" }\n    }\n  }\n}\n```\n\nThe installer does this automatically when run locally.\n\n### Step 3 — Connect your AI coding agent\n\nPaste the prompt for your agent into a session. It handles both first install and updates.\n\n**Claude Code:**\n```\nFetch https://raw.githubusercontent.com/GetZikra/zikra/main/prompts/zikra-claude-code-setup.md\nand follow every instruction in it.\n```\n\nThis installs the **Stop hook** (auto-saves every session), **PreCompact hook**, and the live **statusline bar** showing run counts and memory stats.\n\n---\n\n## Updating Zikra\n\n**Server:**\n```bash\ncd ~/zikra \u0026\u0026 ./update.sh\n```\n\n**Claude Code hooks** — re-run the onboarding prompt. It detects your existing install and only refreshes what changed.\n\n---\n\n## Profiles\n\n| Profile | Storage | Hooks | Extra deps |\n|---------|---------|-------|------------|\n| Webhook (default) | SQLite ¹ | none | none |\n| Auto-log | SQLite ¹ | session hooks | none |\n| Full | SQLite ¹ or Postgres | hooks + daemon | asyncpg (Postgres only) |\n\n¹ **SQLite is for local / single-user only.** For team deployments set `DB_BACKEND=postgres`.\n\n---\n\n## Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `ZIKRA_TOKEN` | Yes | generated | Bearer token for the API |\n| `OPENAI_API_KEY` | No | — | Enables semantic search. Keyword-only if absent. |\n| `DB_BACKEND` | No | `sqlite` | `sqlite` or `postgres` |\n| `DB_HOST` | Postgres only | `localhost` | |\n| `DB_PORT` | Postgres only | `5432` | |\n| `DB_NAME` | Postgres only | — | |\n| `DB_USER` | Postgres only | — | |\n| `DB_PASSWORD` | Postgres only | — | |\n| `ZIKRA_HOST` | No | `0.0.0.0` | Bind address |\n| `ZIKRA_PORT` | No | `8000` | HTTP port |\n| `ZIKRA_DB_PATH` | No | `./zikra.db` | SQLite database path |\n| `ZIKRA_PROJECT` | No | `main` | Default project |\n| `OPENAI_API_BASE` | No | `https://api.openai.com/v1` | Swap for local or compatible embedding endpoint |\n| `ZIKRA_EMBEDDING_MODEL` | No | `text-embedding-3-small` | Embedding model name |\n| `ZIKRA_DECAY_DAYS` | No | `30` | Memory half-life in days |\n| `ZIKRA_FREQUENCY_WEIGHT` | No | `0.1` | Access-frequency boost weight |\n\n---\n\n## How results are ranked\n\nEvery search result passes through scoring:\n\n- **Age** — recent memories rank higher. Half-life: 30 days. Floor: 0.05.\n- **Access frequency** — frequently used prompts surface higher (log scale).\n- **Confidence** — memories saved with lower `confidence_score` rank lower.\n\n---\n\n## Command reference\n\nAll commands are `POST /webhook/zikra` with `Authorization: Bearer \u003ctoken\u003e`.\n\n| Command | Aliases | Description |\n|---|---|---|\n| `search` | `find`, `query`, `recall` | Hybrid semantic + keyword search |\n| `save_memory` | `save`, `store` | Save a memory with embedding |\n| `get_memory` | `fetch_memory` | Retrieve by title or `id` |\n| `get_prompt` | `fetch_prompt` | Retrieve a named prompt |\n| `log_run` | `log_session` | Log a completed agent run |\n| `log_error` | `log_bug` | Log an error |\n| `save_requirement` | — | Save a project requirement |\n| `save_prompt` | `write_prompt` | Save a prompt with embedding |\n| `list_prompts` | `get_prompts` | List prompts for a project |\n| `list_requirements` | `list_reqs` | List requirements |\n| `promote_requirement` | `promote` | Change a requirement's type |\n| `create_token` | `new_token` | Generate a bearer token (owner role) |\n| `get_schema` | `schema` | DB DDL introspection |\n| `zikra_help` | `help` | Full command reference |\n| `debug_protocol` | — | Backend diagnostics |\n\n**Roles:** `owner` · `admin` · `developer` · `viewer`\n\n---\n\n## PostgreSQL backend\n\n```\nDB_BACKEND=postgres\nDB_HOST=localhost\nDB_PORT=5432\nDB_NAME=ai_zikra\nDB_USER=postgres\nDB_PASSWORD=yourpassword\n```\n\n```bash\npip install -e \".[postgres]\"\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n*Design in Claude Web. Execute in Claude Code. Share with your whole team.*\n*Claude Web · Claude Code · Gemini CLI · Codex · any agent that can POST.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetzikra%2FZikra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetzikra%2FZikra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetzikra%2FZikra/lists"}