{"id":48770562,"url":"https://github.com/bkosm/akb","last_synced_at":"2026-04-13T10:01:36.964Z","repository":{"id":350484053,"uuid":"1206977949","full_name":"bkosm/akb","owner":"bkosm","description":"Agentic Knowledge Base MCP","archived":false,"fork":false,"pushed_at":"2026-04-10T14:58:21.000Z","size":11815,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T16:19:33.033Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bkosm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-10T12:55:53.000Z","updated_at":"2026-04-10T14:58:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bkosm/akb","commit_stats":null,"previous_names":["bkosm/akb"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bkosm/akb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkosm%2Fakb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkosm%2Fakb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkosm%2Fakb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkosm%2Fakb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkosm","download_url":"https://codeload.github.com/bkosm/akb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkosm%2Fakb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31747178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-13T10:01:20.108Z","updated_at":"2026-04-13T10:01:36.957Z","avatar_url":"https://github.com/bkosm.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AKB — Agentic Knowledge Base\n\n[![CI](https://github.com/bkosm/akb/actions/workflows/ci.yml/badge.svg)](https://github.com/bkosm/akb/actions/workflows/ci.yml)\n[![Go version](https://img.shields.io/badge/go-1.25%2B-blue)](https://go.dev/dl/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)\n\nAn MCP server that manages knowledge bases as mounted directories. AI agents interact with KBs using standard file tools (Read, Write, Glob, Grep) on local paths — remote storage is transparently mounted via [rclone](https://rclone.org/).\n\n## Installation\n\n### go install\n\n```bash\ngo install github.com/bkosm/akb/go/akb/cmd/akb@latest\n```\n\n### Download binary\n\nPre-built binaries for macOS and Linux (amd64/arm64) are available on the [Releases](https://github.com/bkosm/akb/releases) page.\n\n### From source\n\n```bash\ngit clone https://github.com/bkosm/akb.git\ncd akb\nmake build\n# binary at bin/akb\n```\n\n## Quick start\n\n```bash\n# Local config backend\n./bin/akb.sh local\n\n# S3 config backend (uses env credentials)\n./bin/akb.sh s3\n```\n\n## Architecture\n\n```mermaid\nflowchart TD\n    Agent[\"AI Agent\\n(Cursor / Claude / etc.)\"]\n    MCP[\"AKB MCP Server\\nstdio transport\"]\n    Config[\"Config backend\\nlocal JSON or S3\"]\n    Mount[\"Mount manager\\nrclone FUSE/NFS\"]\n    KB1[\"Local KB\\nplain directory\"]\n    KB2[\"Remote KB\\nS3 / GCS / SFTP\"]\n    Prompts[\"Prompt watcher\\n*.prompt.md\"]\n\n    Agent --\u003e|\"MCP tools\"| MCP\n    MCP --\u003e Config\n    MCP --\u003e Mount\n    Mount --\u003e KB1\n    Mount --\u003e KB2\n    MCP --\u003e Prompts\n    Prompts --\u003e|\"MCP prompts\"| Agent\n```\n\n## Prerequisites\n\n- **Go 1.25+**\n- **rclone** (only needed for remote-backed KBs) — see [docs/rclone-setup.md](docs/rclone-setup.md) or install in one line:\n  ```bash\n  curl -fsSL https://raw.githubusercontent.com/bkosm/akb/main/bin/install-rclone.sh | bash\n  ```\n\n## KB configuration\n\nEach KB entry in the config has these fields:\n\n```json\n{\n  \"rclone_remote\": \":s3,provider=AWS,env_auth=true,region=eu-west-1:my-bucket/prefix/\",\n  \"mount\": \"$HOME/.akb/mounts/my-kb\",\n  \"mount_method\": \"nfs\",\n  \"rclone_args\": {\n    \"vfs-cache-max-size\": \"5G\",\n    \"read-only\": \"\"\n  },\n  \"description\": \"My knowledge base\"\n}\n```\n\n| Field | Required | Description |\n|-------|----------|-------------|\n| `mount` | yes | Local directory path. FUSE/NFS mountpoint when `rclone_remote` is set, otherwise a plain local directory. |\n| `rclone_remote` | no | rclone remote spec. Omit for a plain local directory. Format: `:backend,opt=val:bucket/path`. See [rclone docs](https://rclone.org/overview/#syntax-of-remote-paths). |\n| `mount_method` | no | `\"fuse\"`, `\"nfs\"`, or omit for auto. |\n| `rclone_args` | no | Flag overrides as `{\"flag-name\": \"value\"}` (without `--` prefix). Empty value for boolean flags. Merged on top of defaults. |\n| `description` | no | Human-readable description. |\n\n### Default rclone args\n\nThese are applied to every mount unless overridden via `rclone_args`:\n\n| Flag | Default | Purpose |\n|------|---------|---------|\n| `vfs-cache-mode` | `full` | Full read/write caching |\n| `vfs-cache-max-size` | `1G` | Max local cache size |\n| `vfs-cache-max-age` | `48h` | Cache entry TTL |\n| `dir-cache-time` | `30s` | Directory listing cache |\n| `poll-interval` | `15s` | Remote change polling |\n| `vfs-write-back` | `5s` | Delay before flushing writes to remote |\n| `daemon` | *(bool)* | Run mount in background |\n| `daemon-wait` | `30s` | Max time to wait for daemon startup |\n\n## Prompts\n\nPrompts are auto-discovered from `*.prompt.md` files in mounted KBs and registered as MCP prompts. Drop a file into any KB and it becomes available as a slash-command — no server restart required.\n\n### File format\n\n```markdown\n---\ndescription: Code review with project conventions\narguments:\n  - name: language\n    description: The programming language\n    required: true\n  - name: focus\n    description: Specific areas to focus on\n---\n\nReview my {{.language}} code.{{if .focus}} Focus on: {{.focus}}{{end}}\n```\n\nSee [examples/hello-world.prompt.md](examples/hello-world.prompt.md) for a complete example.\n\n### Naming\n\nThe prompt name is derived from the file path relative to the KB root, minus the `.prompt.md` suffix, prefixed with the KB name:\n\n| File path | KB name | Prompt name |\n|-----------|---------|-------------|\n| `lint.prompt.md` | `my-kb` | `my-kb/lint` |\n| `go/review.prompt.md` | `my-kb` | `my-kb/go/review` |\n\n### Template syntax\n\nThe body uses Go [`text/template`](https://pkg.go.dev/text/template) syntax:\n\n- **Substitution**: `{{.language}}` inserts the argument value\n- **Conditionals**: `{{if .focus}}...{{end}}` renders the block only when the argument is provided\n- **Include**: `{{include \"relative/path.md\"}}` inlines another file\n\n### Role delimiters\n\nBy default the entire body is a single `user` message. To create multi-message prompts, use `@role` headers (any heading level):\n\n```markdown\n## @assistant\n\nYou are a senior {{.language}} engineer.\n\n## @user\n\nReview the code I'm about to share.\n```\n\n## Operational notes\n\n### Async startup mounts\n\nKBs are mounted in a background goroutine that runs **concurrently** with the MCP server. Tools are available immediately, but remote KBs may not yet be mounted when the first request arrives. Use `use_kb` to mount explicitly if needed.\n\n### Config backend concurrency\n\n| Backend | Concurrent-write behaviour |\n|---------|---------------------------|\n| **S3** | Uses `If-Match` / ETag for optimistic locking. Conflicts return `ErrConflict` — callers should re-`Retrieve` and retry. |\n| **localfs** | No locking. Last-writer-wins. Intended for single-process use. |\n\n### Docker wrappers\n\n`bin/akb-docker-s3.sh` and `bin/akb-docker-local.sh` run the MCP server inside a Docker container. They mount `tmp/docker/` (relative to the repo root) as a volume at `/tmp/docker` inside the container and pass `--privileged`.\n\n**Local KBs** (no `rclone_remote`) work normally — set `mount` to `/tmp/docker/\u003cname\u003e` so files are accessible on the host at `tmp/docker/\u003cname\u003e/`.\n\n**Limitation — remote KBs are not supported on macOS with the Docker wrappers.** Docker Desktop uses VirtioFS to share macOS paths into the Docker VM. VirtioFS-backed bind mounts are always `private` propagation, so neither FUSE nor NFS mounts started inside the container are visible from the host. Use the native binary (`bin/akb.sh`) when `rclone_remote` is needed. See [docs/rclone-setup.md](docs/rclone-setup.md) for details.\n\n### Prompt `include` security\n\n`{{include \"path\"}}` is not sandboxed — a `../` traversal can read any file the server process can access. KB prompts are treated as trusted content.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and the PR process.\n\n## Development\n\nSee [AGENTS.md](AGENTS.md) for build commands, architecture, and code conventions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkosm%2Fakb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkosm%2Fakb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkosm%2Fakb/lists"}