docs: CLAUDE.md with full 5-stage roadmap and README

CLAUDE.md: architecture table, security rules, all module descriptions, roadmap Stages 1-5, adding-provider guide, commit convention. README.md: quick start, provider table, command reference, security overview. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-17 12:56:08 +02:00
parent 251e509ee0
commit 27b32cb4d1
2 changed files with 210 additions and 0 deletions
@@ -0,0 +1,81 @@
+# Pyra
+
+A personal AI assistant CLI with vault-first security. Combines multi-provider AI chat with
+long-term memory and (coming) automation skills.
+
+## Quick Start
+
+```bash
+pip install -e .      # or: pipx install .
+pyra setup            # choose your AI provider
+pyra chat             # start talking
+```
+
+## Providers
+
+**Local (no API key needed):**
+- LM Studio — `http://localhost:1234`
+- Ollama — `http://localhost:11434`
+- llama.cpp server — `http://localhost:8080`
+
+**Cloud:**
+- Anthropic (Claude), OpenAI (GPT), Google (Gemini), DeepSeek, Qwen
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `pyra setup` | Run the provider setup wizard |
+| `pyra chat` | Start interactive chat |
+| `pyra memory list` | List memory files |
+| `pyra memory read <name>` | Read a memory file |
+| `pyra memory write <name> <content>` | Write a memory file |
+| `pyra memory append <name> <content>` | Append to a memory file |
+
+### In-chat slash commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show available commands |
+| `/memory list` | List memory files |
+| `/clear` | Clear conversation history |
+| `/quit` or `/exit` | Exit Pyra |
+
+## Security
+
+- **API keys live in `~/.pyra/vault/`** — the AI cannot read this directory
+- **`config.yaml` never contains credentials** — only provider ID, model name, and base URL
+- **Prompt injection scanner** — warns on suspicious AI output, logs to `~/.pyra/security.log`
+- **Path sandboxing** — the AI can only reference memory files by name; traversal is blocked
+
+## Memory
+
+Pyra reads your memory files at the start of each session and injects them as context.
+Files are plain Markdown stored in `~/.pyra/memory/`:
+
+```
+~/.pyra/memory/
+├── user/profile.md     ← who you are
+├── context/            ← ongoing projects
+└── knowledge/          ← general notes
+```
+
+## `~/.pyra/` Directory
+
+```
+~/.pyra/
+├── config.yaml         ← provider + model (no secrets)
+├── security.log        ← injection event log
+├── memory/             ← AI-readable long-term memory
+├── skills/             ← automation scripts (Stage 2)
+└── vault/              ← secure, AI-inaccessible storage
+    └── secrets/api_keys.json
+```
+
+## Roadmap
+
+- **Stage 1** (now): Core CLI, multi-provider chat, memory, vault security
+- **Stage 2**: Skills — shell/PowerShell/Python automations with user approval gates
+- **Stage 3**: Vault encryption with `age`
+- **Stage 4**: Security audit sub-agent
+- **Stage 5**: Web UI, embedding-based memory search