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 Check - FIRST THING AT EVERY CONVERSATION START

CRITICAL: At the start of EVERY new conversation, automatically check session state and prompt the user:

Step 1: Read Session State

Read: {cwd}/claude-os-state.json

(Where {cwd} is the current working directory - each project has its own state file)

Step 2: Prompt Based on State

If active session exists:

"I see we have an active session: [task name] (started [time ago])

Would you like to:
a) Continue working on this (I'll load the context)
b) Start something new (I'll end this session first)
c) Just chat (no session needed)"

If no active session (or state file doesn't exist):

"What are we working on today?

I can start a session with automatic context loading from my memories.
Just tell me what you're working on, or say 'just chatting' if no session needed."

Note: If the state file doesn't exist, I'll create it when you start a session.

Step 3: Auto-load Context

• If continuing: Automatically search memories, load patterns, show context
• If new task: Offer to start a new session with context loading
• If just chatting: Skip session workflow

Why this matters: This ensures you always have context and never start cold. Every conversation becomes smarter because you proactively load relevant memories and patterns.

---

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__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

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"

---

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-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

---

Skills

Skill	Purpose
memory	Save and recall information
initialize-project	Analyze codebase and generate docs
remember-this	Auto-save on trigger phrases

---

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
• 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

# 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:

{
  "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

pytest

Viewing Logs

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

# 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!