Metadata-Version: 2.4
Name: pykorn
Version: 0.3.0
Summary: Atomic knowledge management for AI agents (Capsule)
Author: Korn
License: MIT
Project-URL: Homepage, https://github.com/pisigmac/capsule
Project-URL: Repository, https://github.com/pisigmac/capsule
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.0.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: psycopg[binary]>=3.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: httpx>=0.26.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Dynamic: license-file

<div align="center">
  <h1>Capsule</h1>
  <p><b>Atomic knowledge for AI agents.</b></p>
</div>

Capsule stores one fact per `.capsule.md` file. The search index is SQLite locally, or PostgreSQL when you run Docker.

## Quick start

```bash
pip install korn      # or: pip install pykorn
capsule init          # or: korn init / pykorn init
```

From a clone:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
capsule init
uvicorn services.api.main:app --host 127.0.0.1 --port 9100 --workers 1
```

In another terminal:

```bash
cd frontend
npm install
npm run dev
```

- UI: http://localhost:5173
- API: http://localhost:9100/api/v1
- OpenAPI: http://localhost:9100/docs

Docker (Postgres + API + sync + UI):

```bash
./install.sh
```

- UI: http://localhost:8080
- API: http://localhost:9100

## File format

```markdown
---
id: 7c2a9f14-6b81-4d3e-9a0c-1f8e2b4d6c70
topic: "Auth middleware bypass in staging"
tags: [bug, auth, staging]
freshness: 2026-07-11T00:00:00
source: "incident-4482"
confidence: high
---

Staging skips JWT verification when `X-Debug-Override` is present.
This is intentional for E2E tests. Do not remove; mobile CI depends on it.
```

Creating a capsule via the UI, CLI, or API writes this file. Editing the file updates the index.

## CLI

```bash
capsule new "Auth middleware bypass in staging" -t auth -t bug -c high
capsule search "JWT"
capsule compose -t auth -c medium -m 2000
capsule mcp    # stdio MCP server for agents
```

## MCP

Point an MCP client at `capsule mcp` (stdio). Tools: `search_capsules`, `compose_context`, `get_capsule`, `create_capsule`, `list_stale`.

## Architecture

One API process. It indexes `CAPSULES_DIR` on boot and watches for file changes. Do not run multiple uvicorn workers — SQLite plus the watcher assume a single writer.

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/DEPLOY.md](docs/DEPLOY.md), and [docs/API.md](docs/API.md).

## Tests

```bash
pytest
```

## License

MIT
