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

---

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

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