agent-kb 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Walid Darrai <darraiwalid@gmail.com>
+All rights reserved.
+
+This software and its source code are proprietary and confidential.
+
+No license, right, or permission is granted to any person or entity to use,
+copy, modify, merge, publish, distribute, sublicense, reproduce, or create
+derivative works of this software, in whole or in part, by any means, without
+the prior express written permission of the copyright holder.
+
+Unauthorized use, copying, distribution, or disclosure of this software, or any
+portion of it, is strictly prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# Agent KB
+
+A local-first, project-scoped knowledge base engine for AI agents. Agent KB lives in a hidden `.agent-kb/` folder inside your project, stores entities and relationships as human-readable files (YAML/JSON), and exposes them via a reviewable change-set workflow: agents **propose** changes, humans (or CI) **accept** or **reject** them. The engine offers structured queries, relationship tracing, FTS search, and task-specific context packs — accessible over a CLI or an in-process API.
+
+## Requirements
+
+- Node.js >= 20
+
+## Install / Quickstart
+
+No install needed for one-off use — just run via `npx`:
+
+```bash
+npx agent-kb init
+npx agent-kb context TASK-001
+```
+
+For repeated use in a project, install locally:
+
+```bash
+npm install agent-kb
+```
+
+### Typical flow
+
+```bash
+# 1. Initialise a KB in the current project
+npx agent-kb init
+
+# 2. Check KB health and pending change sets
+npx agent-kb status
+
+# 3. Propose a change set from a JSON file (create/update/link ops)
+npx agent-kb propose change-set.json
+
+# 4. Review what is pending
+npx agent-kb changesets
+
+# 5. Accept or reject a change set by its ID
+npx agent-kb accept CS-001
+npx agent-kb reject CS-002 --reason "duplicate"
+
+# 6. Query the KB
+npx agent-kb get TASK-001
+npx agent-kb find Task
+npx agent-kb related TASK-001
+npx agent-kb trace TASK-001
+npx agent-kb why TASK-001 --in-context FEAT-001
+npx agent-kb search "authentication flow"
+
+# 7. Get a task-specific context pack
+npx agent-kb context TASK-001
+
+# 8. Scan the project for untracked files and validate a change set or entity
+npx agent-kb scan
+npx agent-kb validate CS-001
+
+# 9. Docs and housekeeping
+npx agent-kb docs generate
+npx agent-kb verify
+npx agent-kb reindex
+```
+
+> **Not yet implemented in V1** — these commands are registered and parse correctly but return a `FEATURE_DISABLED` error envelope; do not use them in production flows: `snapshot create`, `export --format json`, `schema apply <file>`.
+
+Full command reference: `npx agent-kb --help` or `npx agent-kb <command> --help`.
+
+Available commands: `init`, `status`, `reindex`, `migrate`, `get <id>`, `find <type>`, `related <id>`, `trace <id>`, `why <id>`, `search <text>`, `context <id>`, `propose <file>`, `validate <idOrFile>`, `accept <id>`, `reject <id>`, `scan`, `verify`, `docs generate`, `changesets`, `schema apply <file>`, `snapshot create`, `export`.
+
+## Embedding (in-process API)
+
+Use the `agent-kb/api` entry point to call the engine directly from Node.js — no subprocess, no network:
+
+```ts
+import { openKb } from 'agent-kb/api';
+
+const kb = openKb({ root: process.cwd() });
+
+// Get a task-specific context pack
+const res = kb.context({ id: 'TASK-001' });
+if (res.ok) {
+  // res.data: ContextPack
+  console.log(res.data);
+} else {
+  // res.error: KbErrorBody  (code + message)
+  console.error(res.error);
+}
+
+// Always release the SQLite handle when done
+kb.close();
+```
+
+Every engine method returns an `Envelope`: `{ ok: true, data: T }` on success or `{ ok: false, error: KbErrorBody }` on failure — it never throws across the API boundary.
+
+The `openKb` function accepts `{ root, clock?, lock?, embeddingProvider? }`. If `.agent-kb/` does not exist yet, the returned engine allows only `init()`; all other methods return a `NOT_FOUND` envelope until you call `init()` and re-open.
+
+## Transports
+
+| Transport | How to use |
+|-----------|-----------|
+| **CLI** | `npx agent-kb <command>` — the `agent-kb` bin ships in `dist/cli/index.js` |
+| **In-process API** | `import { openKb } from 'agent-kb/api'` — same engine, zero overhead |
+| **MCP server** | `npx agent-kb mcp` launches the MCP server over **stdio**. Opt-in and config-gated: it requires `mcp.enabled: true` in `.agent-kb/config.yml` (off by default), otherwise it exits with a `FEATURE_DISABLED` error. Stdio is the only transport (no HTTP/SSE). `createMcpServer` remains internal — it is **not** re-exported from `agent-kb/api`; the CLI bundles it into `dist/cli/index.js`. |
+
+## Vector search
+
+Off by default. Set `search.vector_enabled: true` in `.agent-kb/config.yml` to enable it, and set `search.embedding_provider: 'ollama'` with the `nomic-embed-text` model pulled (`ollama pull nomic-embed-text`). After enabling on an existing KB, run `npx agent-kb reindex` to backfill existing entities into the vector index.
+
+### Search modes
+
+| Mode | What it matches | When to use |
+|------|----------------|-------------|
+| `fts` (default) | Porter-stemmed keyword tokens in `search_fields` | Exact / fuzzy keyword lookup |
+| `semantic` | Meaning similarity via vector embeddings (cosine) | Paraphrase or concept queries — finds what FTS misses |
+| `hybrid` | RRF fusion of FTS + vector rankings | Best of both — surface both keyword and meaning matches |
+
+```bash
+# keyword match (default)
+npx agent-kb search "authentication"
+
+# meaning match — finds "Verifying user credentials" even without the word "login"
+npx agent-kb search "login" --mode semantic
+
+# fused ranking (Reciprocal Rank Fusion)
+npx agent-kb search "login" --mode hybrid
+```
+
+### Error surfaces
+
+- **`FEATURE_DISABLED`** — `semantic` mode returns this error when `search.vector_enabled` is `false` or no embedding provider is configured. `hybrid` degrades gracefully to FTS-only (no error).
+- **`VECTOR_INDEX_FAILED`** — returned by `accept` when the vector-index update fails in the post-commit write-path hook (e.g. the embedding backend errors or is unreachable). Canonical data and FTS are consistent; the vector index is stale until `reindex` is run.
+
+## Project documents
+
+For contributors and deeper understanding:
+
+- `agent-kb-product-spec.md` — external contracts (file formats, JSON ops, error codes, acceptance criteria)
+- `agent-kb-technical-design.md` — internal engineering design (module decomposition, engine API, core types, storage internals, key flows)
+- `TICKETS.md` — index of the 28 implementation tickets: build-order groups, execution order, critical path