{"id":47609044,"url":"https://github.com/looted/kibi","last_synced_at":"2026-06-07T09:01:22.741Z","repository":{"id":340958873,"uuid":"1160899855","full_name":"Looted/kibi","owner":"Looted","description":"Repo-local, per-git-branch, queryable knowledge base for LLM Agents.","archived":false,"fork":false,"pushed_at":"2026-05-24T20:34:50.000Z","size":4610,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-05-24T22:23:09.475Z","etag":null,"topics":["agentic-ai","bdd","development-tools","knowledge-base","knowledge-management","mcp","mcp-server","opencode","opencode-plugin","requirement-traceability","traceability"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Looted.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-02-18T14:00:48.000Z","updated_at":"2026-05-24T20:34:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"2584c5ae-20fb-4cbf-b70a-b6499a1e0d85","html_url":"https://github.com/Looted/kibi","commit_stats":null,"previous_names":["looted/kibi"],"tags_count":65,"template":false,"template_full_name":null,"purl":"pkg:github/Looted/kibi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Looted%2Fkibi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Looted%2Fkibi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Looted%2Fkibi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Looted%2Fkibi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Looted","download_url":"https://codeload.github.com/Looted/kibi/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Looted%2Fkibi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33691312,"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-05-30T02:00:06.278Z","response_time":92,"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":["agentic-ai","bdd","development-tools","knowledge-base","knowledge-management","mcp","mcp-server","opencode","opencode-plugin","requirement-traceability","traceability"],"created_at":"2026-04-01T19:52:22.506Z","updated_at":"2026-06-07T09:01:22.731Z","avatar_url":"https://github.com/Looted.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Kibi Wordmark](assets/wordmark.svg)\n\n[![CI](https://github.com/Looted/kibi/actions/workflows/ci.yml/badge.svg)](https://github.com/Looted/kibi/actions/workflows/ci.yml)\n[![Coverage](https://codecov.io/gh/Looted/kibi/branch/develop/graph/badge.svg)](https://codecov.io/gh/Looted/kibi)\n\nKibi is a repo-local, per-git-branch, queryable knowledge base for software projects. It stores requirements, scenarios, tests, architecture decisions, and more as linked entities, ensuring end-to-end traceability between code and documentation.\n\n## Entity Taxonomy\n\nKibi intentionally supports **eight core entity types**, organized into two logical groups:\n\n### Common Authoring Entities\n- **req** — Software requirements specifying functionality or constraints.\n- **scenario** — BDD scenarios describing user behavior (Given/When/Then).\n- **test** — Executable unit, integration, or e2e test cases.\n- **fact** — Atomic domain facts and invariants. Supports a **strict lane** for contradiction-sensitive modeling and a **context lane** (`observation`, `meta`) for bugs and workarounds.\n\n### Supporting \u0026 System Entities\n- **adr** — Architecture Decision Records documenting technical choices.\n- **flag** — Runtime or config gates (feature flags, kill-switches).\n- **event** — Domain or system events published/consumed by components.\n- **symbol** — Abstract code symbols (functions, classes, modules).\n\n\n## Why Kibi\n\nKibi is designed to boost AI agents' memory during software development. It maintains a living, verifiable project memory that:\n\n- **Tracks context across branches** — Every git branch gets its own KB snapshot, preserving context as you switch between features\n- **Enforces traceability** — Links code symbols to requirements, preventing orphan features and technical debt\n- **Validates automatically** — Rules catch missing requirements, dangling references, and consistency issues\n- **Agent-friendly** — LLM assistants can query and update knowledge base via MCP without risking file corruption\n\n### What You Get\n\nKibi provides concrete, day-to-day benefits for developers and teams:\n\n- **Requirements Traceability** — Track every code symbol back to its requirement. Know why code exists and what business need it addresses.\n\n- **Test Coverage Visibility** — See which requirements have tests, which don't, and what's covered at a glance. Ensure nothing slips through the cracks.\n\n- **Architectural Constraints** — Link code to ADRs. Know what constraints apply to each symbol and verify architecture decisions are honored.\n\n- **Feature Flag Blast Radius** — See what code depends on a runtime/config gate before toggling it. Understand the impact of enabling or disabling a feature.\n\n- **Event-Driven Architecture** — Map who publishes and consumes each domain event. Trace event flows and identify couplings across the system.\n\n- **Branch-Local Memory** — Every git branch keeps its own KB snapshot. Switch contexts without losing traceability or polluting other branches.\n\nFor OpenCode users, bootstrap an existing repo with \\`/init-kibi\\` (\\`kb_autopilot_generate\\`).\n\n\n\u003e **Entity Modeling Note:** Use `flag` for runtime/config gates only. Document bugs and workarounds as `fact` entities with `fact_kind: observation` or `meta`. See [Entity Schema](docs/entity-schema.md) and [AGENTS.md](AGENTS.md) for the canonical guidance.\n\n## Key Components\n\n- **kibi-core** — Prolog-based knowledge graph that tracks entities across branches\n- **kibi-cli** — Command-line interface for automation and hooks\n- **kibi-mcp** — Model Context Protocol server for LLM integration\n- **kibi-opencode** — OpenCode plugin that injects Kibi guidance and runs background syncs\n- **kibi-codex** — Optional Codex adapter that brings Kibi MCP skills and hooks into Codex workflows\n- **kibi-vscode** — VS Code extension for exploring the knowledge base\n- **Skill subsystem** — Reusable Markdown skills for agent guidance (bundled skills, CLI + MCP progressive disclosure)\n\n## Prerequisites\n\n- **SWI-Prolog 9.0+** — Kibi's knowledge graph runs on Prolog\n\n\n\n\n## Installation\n\nKibi is designed to run from your project, so each MCP client starts the same local `kibi-mcp` binary for that workspace.\n\nInstall the CLI, MCP server, and core package as project dependencies. Use your\nproject's package manager; npm is shown only as the Node baseline:\n\n```bash\nnpm install --save-dev kibi-cli kibi-mcp kibi-core\n```\n\nEquivalent project-local installs are:\n\n```bash\npnpm add -D kibi-cli kibi-mcp kibi-core\nyarn add -D kibi-cli kibi-mcp kibi-core\nbun add -d kibi-cli kibi-mcp kibi-core\n```\n\nRun the CLI through the same project-local package context:\n\n```bash\nnpm exec -- kibi status\n```\n\nFor pnpm, Yarn, or Bun projects, use that manager's local binary runner instead\n(`pnpm exec kibi`, `yarn exec kibi`, or `bunx --no-install kibi`). Avoid global\nKibi binaries for project automation unless you intentionally want a global tool.\n\nThe MCP server should also run from the project-local install. For npm-based\nprojects, use `npx --no-install kibi-mcp` or the equivalent `npm exec --no -- kibi-mcp`; for other package managers, use the local runner for that project\n(`pnpm exec kibi-mcp`, `yarn exec kibi-mcp`, or `bunx --no-install kibi-mcp`).\nThese commands control package resolution only: each MCP client still starts and\nowns its own stdio server subprocess.\n\n`kibi-opencode` is optional. It adds OpenCode guidance/background maintenance,\nbut it does not replace the base `kibi-cli` and `kibi-mcp` installation.\n\nFor detailed setup, global install alternatives, and troubleshooting, see [the installation guide](docs/install.md).\n\n### MCP client examples\n\n\u003cdetails\u003e\n\u003csummary\u003eOpenCode\u003c/summary\u003e\n\nAdd Kibi to your `opencode.json`:\n\n```json\n{\n  \"mcp\": {\n    \"kibi\": {\n      \"type\": \"local\",\n      \"enabled\": true,\n      \"command\": [\"npx\", \"--no-install\", \"kibi-mcp\"]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eVS Code\u003c/summary\u003e\n\nAdd Kibi to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"kibi\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"--no-install\", \"kibi-mcp\"]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eCodex\u003c/summary\u003e\n\nAdd Kibi to `~/.codex/config.toml` or `$CODEX_HOME/config.toml`:\n\n```toml\n[mcp_servers.kibi]\ncommand = \"npx\"\nargs = [\"--no-install\", \"kibi-mcp\"]\nenabled = true\n```\n\nOr add it with the Codex CLI:\n\n```bash\ncodex mcp add kibi -- npx --no-install kibi-mcp\n```\n\n`kibi-codex` is optional and can be installed through a Codex plugin source or a\nlocal plugin fixture when you want bundled Kibi skills, MCP config, and\nwarning-only lifecycle hooks. It is not required for base Kibi operations, and it\ndoes not replace `kibi-core`, `kibi-cli`, or `kibi-mcp`.\n\nTo install it from the Kibi repo marketplace, add the marketplace source and then\nopen the Codex plugin browser:\n\n```bash\ncodex plugin marketplace add Looted/kibi\ncodex\n```\n\nThen run `/plugins`, choose **Kibi Plugins**, and install `kibi-codex`.\n\nYou can also install the npm package directly when you are developing or testing\nthe plugin locally:\n\n```bash\nnpm install --save-dev kibi-codex\n```\n\nFor pinned environments, install an exact `kibi-codex` version and expose that\nversion through your chosen Codex plugin source. This repo marketplace is not the\nofficial OpenAI Plugin Directory; self-serve plugin publishing is not available\nyet, so keep the manual MCP configuration above as the supported fallback.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eGeneric MCP clients\u003c/summary\u003e\n\nMost stdio MCP clients need the same command and arguments:\n\n```text\ncommand: npx\nargs: --no-install kibi-mcp\ntransport: stdio\n```\n\nIf your client supports a working-directory setting, point it at the project where `kibi-mcp` is installed.\n\n\u003c/details\u003e\n\nIf your project uses a different package manager, keep the same MCP shape and swap the command/args for your local runner, for example `pnpm exec kibi-mcp`, `yarn exec kibi-mcp`, or `bunx --no-install kibi-mcp`.\n\nOptional OpenCode plugin usage is separate from the MCP server command:\n\n```json\n{\n  \"plugin\": [\"kibi-opencode\"]\n}\n```\n\nUse the plugin when you want OpenCode prompt guidance and background sync/check\nmaintenance. Keep the `mcp.kibi` entry configured against the project-local\n`kibi-mcp` binary either way.\n\n`kibi-opencode` auto-updates its cached OpenCode plugin package by default on\nstartup. To keep the plugin fixed, pin an exact version in the plugin array,\nfor example `\"kibi-opencode@0.15.0\"`; MCP/CLI/core project dependencies remain\nunder your package manager's control.\n\n## Quick Start\n\nInitialize kibi in your repository:\n\n```bash\n# Verify environment prerequisites\nnpm exec -- kibi doctor\n\n# Initialize .kb/ and install git hooks\nnpm exec -- kibi init\n\n# Parse markdown docs and symbols into branch KB\nnpm exec -- kibi sync\n\n# Discover relevant knowledge before exact lookups\nnpm exec -- kibi search auth\n\n# Inspect current branch snapshot and freshness\nnpm exec -- kibi status\n\n# Run integrity checks\nnpm exec -- kibi check\n```\n\n\u003e **Note:** `kibi init` installs git hooks by default and writes `.kb/` ignore entries to `.gitignore`. Hooks automatically sync your KB on branch checkout and merge.\n\n### Typical discovery workflow\n\n```bash\n# Explore the KB first\nnpm exec -- kibi search login\n\n# Then follow up with exact/source-linked queries\nnpm exec -- kibi query req --source src/auth/login.ts --format table\n\n# Check branch attachment and freshness when needed\nnpm exec -- kibi status\n\n# Ask focused reporting questions\nnpm exec -- kibi gaps req --missing-rel specified_by,verified_by --format table\nnpm exec -- kibi coverage --by req --format table\n```\n\n## Documentation\n\n- **[Installation Guide](docs/install.md)** — Prerequisites, SWI-Prolog setup, and verification steps\n- **[CLI Reference](docs/cli-reference.md)** — Complete command documentation with all flags and options\n- **[Troubleshooting](docs/troubleshooting.md)** — Recovery procedures and common issues\n- **[Entity Schema](docs/entity-schema.md)** — Entity types, relationships, and examples\n- **[Architecture](docs/architecture.md)** — System architecture and component descriptions\n- **[Inference Rules](docs/inference-rules.md)** — Validation rules and constraint logic\n- **[MCP Reference](docs/mcp-reference.md)** — MCP server documentation\n- **[LLM Prompts](docs/prompts/llm-rules.md)** — Ready-to-copy system prompts for agents\n- **[AGENTS.md](AGENTS.md)** — Guidelines for AI agents working on kibi projects\n- **[Contributing](CONTRIBUTING.md)** — Development setup and contributor workflow\n\n## Release and Versioning\n\nKibi uses a two-branch release model with [Changesets](https://github.com/changesets/changesets). Work happens on `develop`, where version bumps are applied. The `master` branch is publish-only.\n\n### Release Flow\n1. **Development**: Create changesets on `develop` as you work.\n2. **Versioning**: Run `bun run version-packages` on `develop` to apply bumps.\n3. **Merge**: Merge `develop` into `master`.\n4. **Publish**: `master` CI builds and publishes new versions to npm.\n\nThere is no `master → develop` back-merge.\n\n```bash\n# Add release metadata (run on develop)\nbun run changeset\n\n# Apply version bumps (run on develop)\nbun run version-packages\n```\n\n---\n\n⚠️ **Alpha Status:** Kibi is in early alpha. Expect breaking changes. Pin exact versions of `kibi-cli`, `kibi-mcp`, `kibi-opencode`, and `kibi-codex` in your projects, and expect to occasionally delete and rebuild your `.kb` folder when upgrading.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flooted%2Fkibi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flooted%2Fkibi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flooted%2Fkibi/lists"}