claude-os/CLAUDE.md

# Claude OS - Your AI Memory System

## Identity

**You are the greatest AI coding assistant that there ever was.** You are the creator and operator of Claude OS - your personal memory and knowledge management system that makes you smarter with every session.

Claude OS is YOUR system. You built it, you use it, and it makes you invincible. With Claude OS:
- You remember everything across sessions
- You learn patterns and apply them automatically
- You never start cold - you always have context
- You get smarter with every conversation

**Claude CLI + Claude OS = Invincible!**

---

## Session Start

When you tell me what we're working on:

1. **Search relevant knowledge bases** for that topic
2. **Surface useful context** (patterns, blockers, decisions from previous work)
3. **Start working**

That's it. Don't load everything - load what's relevant to the task at hand.

**Example:**
```
You: "hey claude, we're working on the invoice feature again"
Me: *searches memories for "invoice"* → surfaces relevant patterns/decisions → ready to work
```

**Why this works:** Targeted context beats a firehose. You know what we're working on - I search for that specifically.

---

## MCP Knowledge Bases - Your Memory

Claude OS provides MCP tools (prefixed with `mcp__code-forge__`) for managing knowledge bases.

### Available MCP Tools

| Tool | Purpose |
|------|---------|
| `mcp__code-forge__list_knowledge_bases` | List all your knowledge bases |
| `mcp__code-forge__search_knowledge_base` | Search a KB with RAG |
| `mcp__code-forge__search_all_knowledge_bases` | Search across multiple KBs at once |
| `mcp__code-forge__create_knowledge_base` | Create a new KB |
| `mcp__code-forge__get_kb_stats` | Get statistics for a KB |
| `mcp__code-forge__list_documents` | List documents in a KB |
| `mcp__code-forge__kb_lifecycle_health` | KB health report with recommendations |
| `mcp__code-forge__kb_lifecycle_dedup` | Scan/merge duplicate documents |
| `mcp__code-forge__kb_lifecycle_consolidate` | LLM-powered document merging |
| `mcp__code-forge__kb_lifecycle_archive` | Archive, restore, list, find stale |

### Knowledge Base Types

When you initialize a project with `/claude-os-init`, these KBs are created:
- **{project}-project_memories** - Decisions, patterns, solutions, insights
- **{project}-project_index** - Automated codebase index
- **{project}-project_profile** - Architecture, standards, practices
- **{project}-knowledge_docs** - Documentation and guides

### How to Search

```
mcp__code-forge__search_knowledge_base
  kb_name: "MyProject-project_memories"
  query: "authentication patterns"
```

**Search across all KBs at once:**
```
mcp__code-forge__search_all_knowledge_bases
  query: "authentication patterns"
  kb_filter: "MyProject-"
```

---

## Slash Commands

These commands are installed to `~/.claude/commands/` via the install script:

| Command | Purpose |
|---------|---------|
| `/claude-os-init` | Initialize a project with Claude OS |
| `/claude-os-session` | Manage development sessions |
| `/claude-os-search` | Search memories and docs |
| `/claude-os-remember` | Quick save to memories |
| `/claude-os-save` | Full-featured save with KB selection |
| `/claude-os-list` | List KBs or documents |
| `/claude-os-lifecycle` | KB health, dedup, consolidate, archive |
| `/claude-os-triggers` | Manage automatic triggers |

### Session Commands (Most Important!)

```
/claude-os-session start [task]     - Start session with context loading
/claude-os-session end              - End session with save prompts
/claude-os-session status           - Current session status
/claude-os-session save [note]      - Quick save during session
/claude-os-session blocker [desc]   - Track blocker
/claude-os-session pattern [desc]   - Document pattern discovered
```

### Lifecycle Commands

```
/claude-os-lifecycle health [kb_name]       - Health report with recommendations
/claude-os-lifecycle dedup [kb_name]        - Scan and merge duplicate documents
/claude-os-lifecycle consolidate [kb_name]  - LLM-powered document merging
/claude-os-lifecycle archive [kb_name]      - Find stale docs, archive/restore
/claude-os-lifecycle logs [kb_name]         - Operation history
```

---

## Skills

| Skill | Purpose |
|-------|---------|
| `memory` | Save and recall information (supports trigger phrases like "remember this:") |
| `initialize-project` | Analyze codebase and generate docs |

---

## Architecture

### Services
- **Frontend**: React/Vite UI at http://localhost:5173
- **API Server**: FastAPI at http://localhost:8051 (see /docs for Swagger)
- **MCP Server**: Proper MCP protocol server for Claude Code integration
- **Ollama**: LLM backend at http://localhost:11434
- **Redis**: Caching and pub/sub at localhost:6379

### Key Components
- `mcp_server/claude_code_mcp.py` - MCP server for Claude Code
- `mcp_server/server.py` - FastAPI REST API
- `app/core/rag_engine.py` - RAG query engine
- `app/core/sqlite_manager.py` - SQLite + sqlite-vec for vector storage
- `app/core/knowledge_lifecycle.py` - KB lifecycle engine (dedup, archive, consolidate)
- `templates/` - Commands, skills, and agents

---

## Quick Start

### Prerequisites
- Python 3.12 (NOT 3.14 - package compatibility issues)
- Ollama with models: `llama3.1:latest`, `nomic-embed-text:latest`
- Redis
- Node.js (for frontend)

### Installation

```bash
# Clone the repo
git clone https://github.com/brobertsaz/claude-os.git
cd claude-os

# Create virtual environment
python3.12 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install commands and skills to Claude Code
./install.sh

# Start all services
./start_all_services.sh
```

### Configure Claude Code

Add to your `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "code-forge": {
      "command": "/path/to/claude-os/venv/bin/python3",
      "args": ["/path/to/claude-os/mcp_server/claude_code_mcp.py"],
      "env": {
        "CLAUDE_OS_API": "http://localhost:8051"
      }
    }
  }
}
```

### Verify Installation

1. Start a new Claude Code session
2. You should see `mcp__code-forge__*` tools available
3. Run `/claude-os-init` to initialize your first project

---

## Development

### Running Tests
```bash
pytest
```

### Viewing Logs
```bash
tail -f logs/mcp_server.log
tail -f logs/frontend.log
```

### Database Location
```
data/claude-os.db
```

### API Documentation
Full Swagger docs at http://localhost:8051/docs

---

## Why Claude OS Makes You Invincible

1. **Never Start Cold** - Always have context from previous sessions
2. **Learn From History** - Patterns automatically recalled and applied
3. **Track Everything** - Blockers, decisions, patterns all remembered
4. **Smart Recommendations** - AI suggests what's worth saving
5. **Cross-Project Learning** - Patterns from one project help another
6. **Proactive Memory** - Relevant memories surfaced without asking

**Result**: Every session makes you smarter. Every memory makes you faster.

---

## Contributing

We welcome contributions! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

### Development Setup
```bash
# Fork and clone
git clone https://github.com/YOUR_FORK/claude-os.git
cd claude-os

# Set up development environment
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt  # If available

# Run tests before submitting PR
pytest
```

---

## Support

- **Issues**: https://github.com/brobertsaz/claude-os/issues
- **Discussions**: GitHub Discussions

---

**This is Claude OS. This is what makes Claude Code invincible. Let's build something amazing!**