Skip to main content
Glama
README.md
# personal-os-starter

Minimal, self-contained starter kit for a local-first AI memory engine and FastMCP control plane backed by PostgreSQL 17 (`pgvector`) and YAML state files.

Prompt rules alone are unreliable for enforcing hard limits on weekly workload, spending gates, or state concurrency. This repo moves those checks into plain Python and PostgreSQL so an agent host cannot bypass them.

## What is included

```mermaid
flowchart LR
    HOST["AI CLI / MCP Host"] --> MCP["FastMCP Server"]
    HOST --> SYNC["OCC State Sync"]
    MCP --> STATE["Local YAML State"]
    MCP --> NAT["Stylistics Linter"]
    MCP --> PG["PostgreSQL 17 + pgvector"]
    SYNC --> PG
```

- `src/mcp_server.py` — FastMCP stdio server exposing 7 tools: `query_hybrid_memory`, `ingest_micro_card`, `get_active_facts`, `log_decision_mirror`, `verify_capacity_slack`, `edit_capacity_allocation`, and `check_runway_gate`.
- `src/db/supabase_repo.py` — PostgreSQL/Supabase wrapper with SHA-256 deduplication before embedding calls and Reciprocal Rank Fusion (RRF) search.
- `src/state_sync.py` — Optimistic Concurrency Control (OCC) state synchronizer (`FOR UPDATE` version check in SQL so stale writes fail instead of clobbering newer state).
- `src/stylistics/naturalizer.py` — Zero-LLM stylistics linter checking cliché patterns, sentence-length burstiness (`CV`), and Type-Token Ratio.
- `supabase/migrations/` — Three SQL migrations defining `knowledge_cards` (`halfvec(768)` HNSW + multilingual `'simple'` GIN FTS + `match_knowledge_hybrid`), `executive_state` (OCC upsert), and `user_facts` (JSONB history on contradiction).
- `scripts/audit_public.py` — Zero-dependency scanner that checks for secrets, blocked paths, and custom private markers before publishing.

## Design notes

**Half-precision vector indexing (`halfvec(768)`):** Storing 16-bit floats cuts HNSW memory usage in half (`1,536` vs. `3,072 bytes/row`). In a reference benchmark of the SQL schema (`match_knowledge_hybrid` with `k = 50`, `w_vec = 1.5`, `w_fts = 1.0`) on an `887 MB` Linux VM, P50 latency measured `2.83 ms` (no benchmark harness is bundled in this starter).

**Kingman queuing capacity guard:** Expected queuing delay grows with `rho / (1 - rho)`. `verify_capacity_slack` and `edit_capacity_allocation` enforce `rho <= 0.75` (`21.0h` committed cap out of a `28.0h` weekly pool, keeping `7.0h` slack) and return `HARD_BLOCK` without modifying `state/current_priorities.yaml` on overflow.

**Financial runway gate:** `check_runway_gate` reads `state/pillar_metrics.yaml` and returns `HARD_BLOCK` on discretionary hardware purchases while liquid runway is below target.

## Quickstart

```bash
git clone https://github.com/Giorgoskokk06/personal-os-starter.git
cd personal-os-starter

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp -r state.example state
cp .env.example .env

pytest -v
python3 scripts/audit_public.py
```

Run the MCP server over stdio:

```bash
python3 src/mcp_server.py
```

### Database migrations

Apply the three SQL files in order on PostgreSQL 17 with `pgvector >= 0.7.0`:

```text
supabase/migrations/20261016000001_hybrid_rag_schema.sql
supabase/migrations/20261029000000_executive_state.sql
supabase/migrations/20261102000000_user_facts.sql
```

## Repository layout

```text
src/
  mcp_server.py              # FastMCP server (7 tools)
  state_sync.py              # OCC state sync & HUD builder
  db/supabase_repo.py        # Hybrid RRF retrieval & SHA-256 dedup
  stylistics/naturalizer.py  # Deterministic cliché & burstiness linter
state.example/               # Synthetic YAML/Markdown templates
supabase/migrations/         # pgvector halfvec(768), OCC, and user_facts SQL
scripts/audit_public.py      # Pre-publish secret & marker scanner
tests/                       # 10 unit tests (guards + stylistics)
```

## License

[MIT](LICENSE)