@yurtsever/capsa 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,95 @@
+# capsa
+
+**Your project's knowledge in one capsule — and your coding agent gets exactly what it needs.**
+
+Capsa is a local-first project memory for AI coding agents (Claude Code, Cursor, Continue, Cline). It indexes the knowledge that already lives in your repo — runbooks, tickets, plans, decisions, `CLAUDE.md`/`AGENTS.md`, Cursor rules, Claude Skills — and hands the agent the *smallest* relevant slice of it, over MCP, for every task.
+
+Not more context. Less, and the right one. Every delivery is logged, so you can see what the agent saw and how many tokens it cost.
+
+> Status: **MVP in progress.** Weeks 1–2 (indexer + MCP) are usable from source; the cockpit UI comes after the retrieval proof. See [`docs/idea/04-mvp-konzept.md`](docs/idea/04-mvp-konzept.md).
+
+## Quick start (from source)
+
+Requirements: Node ≥ 22.13, bun, and [Ollama](https://ollama.com) with the embedding model:
+
+```sh
+ollama pull bge-m3
+```
+
+```sh
+git clone https://github.com/yurtsever/capsa
+cd capsa
+bun install
+bun run build
+
+# index a project (writes <project>/.capsa/index.db — git-ignore it)
+node packages/cli/dist/index.js index ~/code/my-project
+
+# what would an agent get for this task?
+node packages/cli/dist/index.js search "add rate limiting to the login endpoint" ~/code/my-project
+
+# where does the project stand?
+node packages/cli/dist/index.js state ~/code/my-project
+```
+
+Try it on capsa itself: `node packages/cli/dist/index.js index .` — the repo's own docs, ADRs and tickets are the first test corpus.
+
+## Wire it into your agent (MCP)
+
+```sh
+claude mcp add capsa -- node /abs/path/to/capsa/packages/cli/dist/index.js mcp /abs/path/to/project
+```
+
+Tools the agent gets:
+
+| Tool | What it does |
+|---|---|
+| `get_context(task, maxTokens?)` | the smallest relevant set of project knowledge for a task (default budget 1500 tokens) |
+| `get_project_state()` | open tickets/plans, recent decisions, recently changed knowledge |
+| `record_decision(title, body, related?)` | write a decision back so future sessions retrieve it |
+
+Once published, `npx capsa …` replaces the `node packages/cli/dist/index.js …` prefix.
+
+## What it indexes
+
+| Kind | Where | Ranking signals |
+|---|---|---|
+| Instruction files | `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.cursor/rules/*.mdc`, `SKILL.md` | kind |
+| Runbooks / wiki | `docs/**/*.md`, `runbooks/**/*.md` | recency |
+| Decisions | `docs/adr/**/*.md`, `decisions/**/*.md` | recency, kind |
+| Tickets | `tickets/**/*.md`, `docs/tickets/**/*.md` | **status** from checkboxes or `status:` frontmatter, recency |
+| Plans | `plans/**/*.md` | status, recency |
+
+Adding a source is one adapter package (`packages/adapter-*`) — the scanner does not change.
+
+## How retrieval works
+
+Vector search (bge-m3 via Ollama, [sqlite-vec](https://github.com/asg017/sqlite-vec)) and full-text search (FTS5) are fused with reciprocal rank fusion, then weighted by what the source can honestly claim about itself: how recent it is, whether it is still live (`in-progress` beats `done`), and what kind of knowledge it is. Results are filled greedily into the token budget, at most two chunks per file.
+
+All of it lives in one SQLite file per project, `.capsa/index.db`. Every weight is a hypothesis; the `context_log` table is how they get corrected.
+
+## The web UI
+
+`node packages/cli/dist/index.js [paths…]` starts the instruction-file library from skillary on `127.0.0.1:4820`. It is being redesigned into the cockpit (goal – state – history, context inspector, instructions) after the retrieval gate.
+
+## Local-first, by construction
+
+- The server binds `127.0.0.1`, never `0.0.0.0`.
+- Capsa never edits your files. It writes exactly two things: its own index under `.capsa/`, and decisions an agent explicitly records.
+- No telemetry, no accounts, no network beyond `localhost:11434` (Ollama).
+
+## Development
+
+See [`docs/runbooks/development.md`](docs/runbooks/development.md) and [`CLAUDE.md`](CLAUDE.md).
+
+```sh
+bun run build && bun run test && bun run typecheck
+```
+
+## Heritage
+
+Capsa grew out of [skillary](https://github.com/yurtsever/skillary), a read-only library for AI instruction files. The scanner, adapters, server and UI are its; see [`docs/adr/001-build-on-skillary.md`](docs/adr/001-build-on-skillary.md).
+
+## License
+
+MIT