Skip to main content
Glama

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

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.

Related MCP server: Verantyx Vera MCP Server

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

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:

python3 src/mcp_server.py

Database migrations

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

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

Repository layout

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Provides LLM agents with hallucination-free external memory and knowledge tools, including ask, remember, forget, math, and code reasoning, with deterministic, traceable outputs.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to store, search, assemble, and manage local-first memories through seven MCP tools, including conversation turns, feedback, status, and dashboard access without cloud dependencies.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to use a neuro-symbolic memory fabric with bi-temporal knowledge graph and holographic VSA, providing tools for adding, searching, temporal queries, auditing, and proving memories with cryptographic provenance and zero-LLM ingest.
      2
      Apache 2.0