Skip to content

CLAUDE.md

Latest commit

 

History

History
154 lines (107 loc) · 6.54 KB

CLAUDE.md

File metadata and controls

154 lines (107 loc) · 6.54 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Phantom Logos v1.2.1 is a sovereign, local-first agentic OS built on Python 3.12+. It implements a 3-tier hierarchical agent architecture (RuFlow) with 14-axis persistent memory (Mnemosyne), formal verification, and provider-agnostic LLM routing.

Commands

# Automated install and setup
python scripts/bootstrap.py

# Run all tests
pytest tests/ -v

# Run a single test file
pytest tests/path/to/test_file.py -v

# Run smoke tests only
pytest tests/ -m smoke -v

# Lint (ruff)
ruff check .
ruff format .

# Type check (pyright only -- mypy not used)
D:/Hank/.venv/Scripts/python -m pyright src/

# Database migrations
alembic upgrade head
alembic revision --autogenerate -m "description"

# Health check (14-axis system)
python scripts/health_check_14_axes.py

# Generate L0 auth token (required for write operations, 60s window)
python scripts/create_l0_token.py

# CLI interface
python scripts/hermes_cli.py

# Flush VRAM between heavy model transitions
python scripts/morpheus_flush.py

# Seed 14-axis memory on fresh setup
python scripts/seed_14_axes.py
python scripts/seed_semantic.py

Architecture

Agent Tiers (RuFlow v1.2.0)

  • L0 (Hank): Human authority. All write/system actions require explicit L0 consent + valid L0_AUTH_TOKEN.
  • L1 (Sophia): Strategic gateway. Full 14-axis Mnemosyne integration. Handles planning and architectural decisions.
  • L2 (Clotho): Executor. Runs qwen3.5-4b-ud (coding), ministral-3b-ud (routine), deepscaler-1.5b (rapid). Code generation and tool orchestration via GatewayArchitrave.
  • L3 (Lachesis): Auditor. Runs phi-4-mini-ud (logic) or qwen2.5-coder-3b (code/math). Formal verification and adversarial auditing.

Agent definitions are declarative YAML files in agent/ (sophia.yaml, clotho.yaml, lachesis.yaml, etc.). Hot-loadable skills live in agent/skills/.

Source Modules (src/)

  • architrave: Central gateway client, model registry, context cache, entity extraction, OTL engine. The unified routing layer.
  • clotho: LangGraph orchestrator (orchestrator.py), task execution, skill loading, agent bootstrap.
  • atropos: Context pruning, observability, matryoshka compression service.
  • lachesis: Self-tuner, snapshot manager, file watchdog.
  • ankyra: Anchor/embedding generation.
  • muscle: Local runtime bridge (Ollama/llama.cpp), reranker.
  • tools: MCP tool implementations (34 tools).
  • utils: Config, logging, rate limiting, security, token budget management.

14-Axis Mnemosyne Memory

Persistent memory across 14 cognitive axes stored in SQLite + LanceDB (data/). Axes: Episodic (1), Procedural (2), Goals (3), Temporal (4), Spatial/Graph (5), Semantic (6), Operational (7), Meta-Cog (8), Tone (9), Rational (10), Verification (11), Efficiency (12), Cross-Session Patterns (13), Visual (14).

All strategic claims in outputs must cite the relevant axis as [SRC:axis_N].

Sovereign Knowledge Base (.antigravity/)

  • CONSTITUTION.md — Core governance laws
  • rules.json — Machine-readable governance rules (always override task-completion urges)
  • tools.md — MCP tool inventory
  • topography.md — Live codebase map
  • walkthroughs/main_walkthrough.md — Phase execution history
  • audit/ — Formal audit logs

Formal Verification Pipeline

4-stage chain: AST analysis → QWED → SymPy → Z3 SAT solver. Triggered for any logic-critical or mathematical change. See scripts/sovereign_audit.py.

Key Constraints

VRAM Budget

Total: 7.0 GB. OS reserve: 1.0 GB. Never load two heavy models (>3 GB) concurrently. Every heavy model transition requires Morpheus.flush() first. LocalRuntime must use dynamic -ngl for layer offloading.

Communication Protocol (BA-01)

  • L0 chat and user-facing .md artifacts: Turkish
  • Code, comments, logs, config, agent internals: English (ASCII-only only — no Turkish characters)
  • EMOJI_BAN: Emojis and special character decorations are strictly prohibited everywhere
  • Timestamps: Use [HH:MM AM/PM PT] format in all action logs

Write Operation Governance

Any code edit, config change, or deletion requires:

  1. Explicit L0 consent ("basla" / "yurut")
  2. Valid L0_AUTH_TOKEN (60-second window, generated by scripts/create_l0_token.py)

Pre-write audit: identify 2 potential breaking points before any write operation.

Tool Priority

Agents must use SLM MCP tools (mcp_slm_*) and Muscle tools for status checks, context ops, and logging. Raw filesystem/bash access for these operations is prohibited.

3-Strike Error Rule

If an error persists with >80% code similarity across retries, maximum 3 retries allowed. After the 3rd failure, stop and deliver a post-mortem.

Development Flow

Every implementation phase requires three artifacts stored in .md files:

  1. implementation_plan.md — Architecture and strategy
  2. task.md — Granular TODOs (no skipping steps)
  3. scratch_book.md — Continuous diary for context, errors, reminders

The final step of every phase must be "Test & Verification" with evidence (logs, test output).

Available Skills

  • /audit — Full system integrity audit; follow with /remember to consolidate
  • /think — Sequential reasoning for complex architectural or logic decisions
  • /recall — Query Mnemosyne/KG memory before making assumptions about system state
  • /investigate — Sovereign debug protocol for persistent or cascading errors
  • /topography — Regenerate live codebase map in .antigravity/topography.md
  • /sprint — Sprint contract negotiation (DOD, scope, timeline)
  • /security — Security audit before any auth/crypto/governance change
  • /guard — Full sovereign guard mode for high-risk sessions

Session Management

  • Resume latest session: claude --continue
  • Choose session to resume: claude --resume
  • Between unrelated tasks: /clear (full context reset)
  • After long exploration before coding: /compact

Parallel Development

For refactors touching 10+ files (RuFlow tier changes, Mnemosyne axis migrations):

  • Use worktrees: claude --worktree <branch> for isolated parallel sessions
  • Use /batch for automated multi-file transformations with agent decomposition

Testing

  • Tests live in tests/. Pytest asyncio mode is auto.
  • CI runs against Python 3.11 and 3.12 with env vars PYTHONPATH=., LLM_BINARY_DIR=./bin, LLM_MODEL_DIR=./models.
  • data/ directory (SQLite, LanceDB) is gitignored and must be seeded locally before running memory-dependent tests.