{"id":51228343,"url":"https://github.com/natorus87/kiwiki","last_synced_at":"2026-06-28T13:31:17.093Z","repository":{"id":364843087,"uuid":"1269264297","full_name":"natorus87/kiwiki","owner":"natorus87","description":"KIWiki — Your AI-powered self-hosted wiki","archived":false,"fork":false,"pushed_at":"2026-06-14T18:02:53.000Z","size":459,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T19:20:38.866Z","etag":null,"topics":["ai","docker","fastapi","knowledge-base","markdown","mcp","model-context-protocol","note-taking","python","self-hosted","wiki"],"latest_commit_sha":null,"homepage":null,"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/natorus87.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"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":null,"dco":null,"cla":null}},"created_at":"2026-06-14T13:56:12.000Z","updated_at":"2026-06-14T18:02:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/natorus87/kiwiki","commit_stats":null,"previous_names":["natorus87/kiwiki"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/natorus87/kiwiki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natorus87%2Fkiwiki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natorus87%2Fkiwiki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natorus87%2Fkiwiki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natorus87%2Fkiwiki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/natorus87","download_url":"https://codeload.github.com/natorus87/kiwiki/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natorus87%2Fkiwiki/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34890795,"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-06-28T02:00:05.809Z","response_time":54,"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":["ai","docker","fastapi","knowledge-base","markdown","mcp","model-context-protocol","note-taking","python","self-hosted","wiki"],"created_at":"2026-06-28T13:31:16.464Z","updated_at":"2026-06-28T13:31:17.088Z","avatar_url":"https://github.com/natorus87.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kiwiki\n\n[![Website](https://img.shields.io/badge/web-kiwiki.xyz-blue)](https://kiwiki.xyz)\n![Docker Hub](https://img.shields.io/docker/v/natorus87/kiwiki?label=Docker%20Hub\u0026logo=docker)\n![Python](https://img.shields.io/badge/python-3.12-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n\nkiwiki is a self-hosted **Agent Harness** and Markdown knowledge base for humans and AI agents. Notes stay as regular files on disk, the web UI gives you a searchable wiki, and the built-in MCP server lets tools such as Claude Code, Codex, OpenCode, Cursor, ChatGPT, OpenClaw, Hermes, and any MCP client read and write the same knowledge base in parallel.\n\nNo hosted account is required. Your Markdown files are the source of truth.\n\nVisit **[kiwiki.xyz](https://kiwiki.xyz)** for the project website, FAQ, agent integration guides, and hosting options.\n\n## Screenshots\n\n![kiwiki dashboard](docs/assets/screenshots/kiwiki-dashboard.png)\n\n![kiwiki note view](docs/assets/screenshots/kiwiki-note-view.png)\n\n![kiwiki search](docs/assets/screenshots/kiwiki-search.png)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/screenshots/kiwiki-mobile.png\" alt=\"kiwiki mobile layout\" width=\"360\"\u003e\n\u003c/p\u003e\n\n## Features\n\n- **Multi-Agent Harness** — Central knowledge base for Claude Code, Codex, OpenCode, Cursor, ChatGPT, OpenClaw, Hermes, and any MCP-compatible agent. All agents read and write the same wiki in parallel.\n- **Markdown files with YAML frontmatter** — Your file system is the source of truth. No proprietary database, no vendor lock-in, simple to back up.\n- **100 % privacy** — Self-hosted on your infrastructure. No cloud, no telemetry, no vendor lock-in.\n- **Per-user isolated wiki folders** under `/data/\u003cusername\u003e/` with role-based access (`read` / `write` / `admin`).\n- **SQLite FTS5 full-text search** — Search thousands of Markdown files in milliseconds, including via MCP from your AI.\n- **Responsive web UI** — FastAPI with Jinja2, HTMX, and Toast UI Editor. Works from 4K desktop to mobile.\n- **Streamable HTTP MCP endpoint** at `/mcp` (legacy HTTP/SSE at `/mcp/sse`) with OAuth 2.1 authorization-code flow for ChatGPT-style connectors.\n- **Docker Compose and Helm** — One command to start. Kubernetes-ready.\n\n## Quick Start\n\n```bash\ngit clone https://github.com/natorus87/kiwiki.git\ncd kiwiki\ncp .env.example .env\ndocker compose up -d\n```\n\nOpen the web UI:\n\n```text\nhttp://localhost:8082\n```\n\nUse the API key configured in `KIWIKI_USERS`.\n\n## Configuration\n\nAll runtime configuration is done through environment variables.\n\n| Variable | Default | Description |\n|---|---:|---|\n| `KIWIKI_DATA_DIR` | `/data` | Data directory for all wiki files |\n| `KIWIKI_USERS` | required | Built-in users in `user:key:role` format, comma-separated |\n| `KIWIKI_BASE_URL` | `http://localhost:8080` | Public base URL used in MCP and OAuth metadata |\n| `KIWIKI_LOG_LEVEL` | `INFO` | Python log level |\n| `KIWIKI_TRUST_PROXY` | `true` | Use secure cookies behind a TLS reverse proxy |\n| `KIWIKI_CORS_ORIGINS` | `*` | Comma-separated list of allowed CORS origins |\n| `KIWIKI_RATE_LIMIT_ENABLED` | `true` | Enables login, read, and write rate limits |\n| `KIWIKI_OAUTH_TOKEN_SECRET` | derived | Optional stable secret for signing OAuth MCP tokens |\n| `KIWIKI_OAUTH_TOKEN_TTL_SECONDS` | `86400` | OAuth access-token lifetime |\n| `KIWIKI_OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `2592000` | OAuth refresh-token lifetime |\n\nExample:\n\n```env\nKIWIKI_DATA_DIR=/data\nKIWIKI_USERS=admin:\u003cadmin-api-key\u003e:admin,writer:\u003cwriter-api-key\u003e:write,reader:\u003creader-api-key\u003e:read\nKIWIKI_BASE_URL=https://kiwiki.example.com\nKIWIKI_TRUST_PROXY=true\nKIWIKI_CORS_ORIGINS=https://kiwiki.example.com\nKIWIKI_OAUTH_TOKEN_SECRET=\u003crandom-token-signing-secret\u003e\n```\n\nGenerate strong keys with:\n\n```bash\nopenssl rand -hex 24\n```\n\nDo not commit real API keys, OAuth secrets, `.env` files, or local wiki data.\n\n## User Model\n\nEach user gets a separate wiki root:\n\n```text\n/data/admin/\n/data/alice/\n/data/bob/\n```\n\nUsers cannot read or search another user's files. Web UI requests, REST API calls, search, and MCP tools all run in the authenticated user's namespace.\n\nRoles:\n\n| Role | Permissions |\n|---|---|\n| `read` | Read files and search |\n| `write` | Read plus create, edit, move, and reindex |\n| `admin` | Full access, including delete and user management |\n\n## ChatGPT and MCP\n\nkiwiki exposes MCP over Streamable HTTP:\n\n```text\nhttps://kiwiki.example.com/mcp\n```\n\nFor ChatGPT custom connectors, configure the MCP endpoint as the connector URL. If OAuth is enabled, ChatGPT discovers:\n\n```text\n/.well-known/oauth-protected-resource/mcp\n/.well-known/oauth-authorization-server/mcp\n```\n\nThe OAuth flow uses:\n\n- Authorization code with PKCE\n- Signed access tokens\n- Refresh tokens\n- The `resource` parameter expected by MCP clients\n- Client ID Metadata Document style client IDs used by ChatGPT\n\nFor public deployments, set a stable `KIWIKI_OAUTH_TOKEN_SECRET`. This keeps connector tokens valid across container restarts while still allowing API-key rotation to revoke access.\n\nDirect bearer-token access is also supported:\n\n```bash\ncurl https://kiwiki.example.com/mcp \\\n  -H \"Authorization: Bearer \u003capi-key\u003e\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'\n```\n\n## Usage as AI Memory\n\nConfigure your AI tools to use kiwiki as persistent memory. The following instruction works for ChatGPT (Custom Instructions → Personalization), Claude (Personalization), and coding agents:\n\n\u003e Use kiwiki as my persistent memory. When asked about projects, decisions, recurring topics, personal preferences, or work context, first briefly check kiwiki. Use existing notes as context.\n\u003e\n\u003e Save new important information in kiwiki when it might be useful later: preferences, decisions, project knowledge, workflows, important facts, and open items. Prefer to update existing files rather than creating new ones. Organize according to the existing structure: `/projects`, `/decisions`, `/notes`, `/shared` and `/user`. Write short Markdown notes with frontmatter. Do not delete anything without explicit instruction. Also ask in longer chats whether you should save something.\n\nFor coding agents (Claude Code, Codex, OpenCode, Cursor), add this instruction to your project's `AGENTS.md`, `CLAUDE.md`, or equivalent configuration file.\n\n### Agent Harness Setup\n\nWhen using kiwiki as the Agent Harness for your project, instruct coding agents to connect to kiwiki via MCP. Add the following block to your project's `AGENTS.md` or `CLAUDE.md`:\n\n\u003e This project uses **kiwiki** as its Agent Harness and persistent memory.\n\u003e\n\u003e **MCP connection** — Connect to the kiwiki MCP server using the appropriate command for your tool:\n\u003e - Claude Code: `claude mcp add kiwiki http://localhost:8082/mcp --header \"Authorization: Bearer \u003capi-key\u003e\"`\n\u003e - Codex: `codex mcp add kiwiki http://localhost:8082/mcp --header \"Authorization: Bearer \u003capi-key\u003e\"`\n\u003e - OpenCode: configure MCP server in opencode.json\n\u003e - Cursor: configure MCP server in `.cursor/mcp.json`\n\u003e\n\u003e Once connected, use kiwiki as persistent memory (see usage instruction above).\n\nThis ensures every coding agent working on the project automatically connects to the shared knowledge base.\n\n## MCP Tools\n\nThe MCP server exposes tools for common wiki workflows, grouped by required role:\n\n### Read (any role)\n\n`read_file` · `read_many` · `read_lines` · `fetch` · `search` · `grep` · `find` · `list_files` · `list_all_files` · `file_info` · `read_index` · `recent_files` · `backlinks` · `related_files` · `search_status` · `whoami`\n\n### Write (write role or admin)\n\n`write_file` · `write_many` · `chunked_write` · `edit` · `append_file` · `create_note` · `upsert_note` · `update_frontmatter` · `preview_edit` · `replace_many` · `build_index` · `reindex_all` · `tag_index` · `move_file`\n\nFor autonomous agents, prefer `write_many` when updating several files and `chunked_write` when a large file or flaky client payload limit makes a single `write_file` / `append_file` call unreliable. Ordinary create, update, append, and index-refresh operations do not require confirmation; clients should ask before deleting files or running destructive reorganizations. `chunked_write` keeps temporary chunks in process memory for `KIWIKI_MCP_UPLOAD_TTL_SECONDS` (default `3600`) and limits staged uploads with `KIWIKI_MCP_MAX_UPLOAD_BYTES` (default `10485760`) and `KIWIKI_MCP_MAX_UPLOAD_CHUNKS` (default `1000`).\n\n### Admin (admin role only)\n\n`validate_wiki` · `delete_file` · `sort`\n\n## Local Development\n\nCreate a virtual environment and install dependencies:\n\n```bash\npython3.12 -m venv .venv\n. .venv/bin/activate\npython -m pip install -r requirements-dev.txt\nnpm ci\n```\n\nRun the app:\n\n```bash\nKIWIKI_DATA_DIR=./data \\\nKIWIKI_USERS=\"admin:dev-key:admin\" \\\nKIWIKI_BASE_URL=\"http://127.0.0.1:8080\" \\\nKIWIKI_TRUST_PROXY=false \\\nuvicorn app.main:app --host 127.0.0.1 --port 8080 --reload\n```\n\nBuild the frontend motion bundle:\n\n```bash\nnpm run build:motion\n```\n\nRun checks:\n\n```bash\nruff check app tests\npytest -q\nnpm audit --audit-level=high\ndocker build -t kiwiki:test .\n```\n\n## Docker\n\nThe default Compose file builds the local image and serves the app on port `8082`:\n\n```bash\ndocker compose up -d\ndocker compose logs -f kiwiki\n```\n\nPersistent data is mounted at:\n\n```text\n./data:/data\n```\n\nFor public deployments, move real secrets into `.env` or your secret manager.\n\n## Helm\n\nA Helm chart is available under `charts/kiwiki`.\n\nInstall example:\n\n```bash\nhelm upgrade --install kiwiki ./charts/kiwiki \\\n  --set env.KIWIKI_USERS=\"admin:\u003cadmin-api-key\u003e:admin\" \\\n  --set env.KIWIKI_BASE_URL=\"https://kiwiki.example.com\" \\\n  --set env.KIWIKI_OAUTH_TOKEN_SECRET=\"\u003crandom-token-signing-secret\u003e\"\n```\n\nReview `charts/kiwiki/values.yaml` before deploying to production.\n\n## Repository Hygiene\n\nThe repository includes:\n\n- GitHub Actions CI for Ruff, Pytest, frontend build, and Docker build\n- Dependabot configuration for Python, npm, and GitHub Actions\n- Issue and pull request templates\n- Security policy\n- MIT license\n\nIgnored local artifacts include `.venv/`, `node_modules/`, `data/`, Python caches, test caches, and local agent configuration.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md).\n\nImportant operational rules:\n\n- Use strong random API keys.\n- Set `KIWIKI_TRUST_PROXY=true` behind HTTPS.\n- Restrict `KIWIKI_CORS_ORIGINS` in production.\n- Set `KIWIKI_OAUTH_TOKEN_SECRET` for public MCP/OAuth deployments.\n- Do not publish local wiki data or deployment secrets.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatorus87%2Fkiwiki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnatorus87%2Fkiwiki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatorus87%2Fkiwiki/lists"}