Metadata-Version: 2.4
Name: sidecar-ai
Version: 3.0.0a1
Summary: Project memory for AI coding agents — persistent knowledge that survives across sessions
Author: Okasha Mohammed
License-Expression: MIT
Project-URL: Homepage, https://github.com/okasha-mo/sidecar
Project-URL: Repository, https://github.com/okasha-mo/sidecar
Project-URL: Issues, https://github.com/okasha-mo/sidecar/issues
Keywords: llm,ai-coding,claude,context-management,developer-tools,project-memory,knowledge-management
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: click>=8.1.7
Requires-Dist: rich>=13.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.3; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: ruff>=0.1.9; extra == "dev"
Requires-Dist: types-pyyaml; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: mkdocs>=1.5.3; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.3; extra == "dev"
Provides-Extra: ml
Requires-Dist: sentence-transformers>=2.3.1; extra == "ml"
Requires-Dist: scikit-learn>=1.4.0; extra == "ml"
Requires-Dist: numpy>=1.26.0; extra == "ml"
Provides-Extra: mcp
Requires-Dist: mcp>=0.1.0; extra == "mcp"
Dynamic: license-file

# Sidecar

**Project memory for AI agents.**

Sidecar gives your AI coding agent persistent memory across sessions. Decisions, constraints, lessons, and relationships are stored locally and surfaced automatically when relevant — so your agent stops repeating questions, forgetting architecture, and drifting off course.

```bash
pip install sidecar-ai
cd your-project
sidecar init
sidecar learn "We use Pydantic for all API schemas"
sidecar recall "API validation"
```

---

## Why Sidecar?

AI coding agents work great for simple tasks but degrade as projects grow:

- Context drift — the agent forgets decisions made three sessions ago
- Repeated questions — asks "what database do we use?" every time
- Lost architecture — constraints and patterns aren't carried forward
- No learning — the same mistakes get made twice

Sidecar solves this with a local knowledge store that integrates into your agent's workflow. Knowledge is captured once and recalled automatically.

---

## Quickstart

### Install

```bash
# From PyPI (requires Python 3.11+)
pip install sidecar-ai

# Optional: semantic search (adds ~2GB for sentence-transformers)
pip install 'sidecar-ai[ml]'

# From source
git clone https://github.com/okasha-mo/sidecar.git
cd sidecar && pip install -e .
```

### Initialize a project

```bash
cd your-project
sidecar init
```

This creates a `.sidecar/` directory with a SQLite database and config. Add `.sidecar/` to `.gitignore` or commit it — your choice.

### Capture knowledge

```bash
# Decisions — what you chose and why
sidecar learn "Use PostgreSQL for the main database, SQLite for local dev"

# Constraints — rules that must hold
sidecar learn --constraint "All API endpoints must return X-Request-ID header"

# Lessons — things learned the hard way
sidecar learn --lesson "Changing token format requires a mobile release first"

# Relationships — how things connect
sidecar learn --relationship "Auth service depends on Redis for session storage"
```

### Recall knowledge

```bash
sidecar recall "database"
sidecar recall "authentication" --type constraint
sidecar recall "what caching strategy do we use?"
```

### Generate documents

```bash
# Generate a CLAUDE.md from your knowledge store
sidecar compile -o CLAUDE.md

# Generate a session primer
sidecar compile --format primer

# Generate a SKILL.md
sidecar compile --format skill -o SKILL.md
```

---

## Core Commands

| Command | What it does |
|---------|-------------|
| `sidecar init` | Initialize sidecar in the current project |
| `sidecar learn "..."` | Store a decision, constraint, lesson, or relationship |
| `sidecar recall "..."` | Search the knowledge store |
| `sidecar brief "task"` | Get a context brief for a specific task |
| `sidecar compile` | Compile knowledge into CLAUDE.md, SKILL.md, or primer |
| `sidecar status` | Show project health — item counts, phase, staleness |
| `sidecar reflect` | End-of-session capture + write primer for next session |
| `sidecar onboard` | Auto-discover knowledge from README, ADRs, config files |
| `sidecar recipe search "react"` | Find curated knowledge bundles |
| `sidecar recipe install fastapi` | Install a recipe into your knowledge store |
| `sidecar depth` | Show or set the project phase |
| `sidecar upgrade production` | Audit code and upgrade to a target phase |
| `sidecar conflicts` | Detect contradictory knowledge items |
| `sidecar stale` | List knowledge items that may need review |
| `sidecar export` | Export knowledge as portable JSON |
| `sidecar import README.md` | Import knowledge from markdown files |

Run `sidecar --help` or `sidecar <command> --help` for full options.

---

## Claude Code Integration

Sidecar ships with hooks that integrate directly into Claude Code, so knowledge is injected into prompts and captured at session end automatically.

```bash
# One-command setup: init + install hooks + install skill
sidecar setup

# Or install individually
sidecar install-hooks    # Auto-inject knowledge into Claude prompts
sidecar install-skill    # Add /sidecar skill to Claude Code
```

Once installed:
- **Prompt hook** — relevant knowledge is appended to every prompt automatically
- **Stop hook** — session insights are captured when Claude finishes
- **Skill** — use `/sidecar` in Claude Code for quick access

---

## Project Phases

Sidecar tracks your project's maturity phase. Knowledge items can be scoped to phases — production constraints won't clutter prototype sessions.

```bash
sidecar depth                    # Show current phase
sidecar depth production         # Set phase manually
sidecar upgrade production       # Audit code gaps, then upgrade
```

Phases: `prototype` → `mvp` → `production` → `scale`

The upgrade command scans your source code for real issues (TODOs, hardcoded config, missing tests, bare excepts) and offers to capture findings as constraints.

---

## Recipes

Curated knowledge bundles for common stacks. Install best practices in seconds.

```bash
sidecar recipe search "python"       # Find recipes
sidecar recipe inspect fastapi       # Preview contents
sidecar recipe install fastapi       # Install into knowledge store
sidecar recipe list                  # Show installed recipes
```

Built-in recipes: `fastapi`, `nextjs`, `cli-python`. Items are deduplicated against your existing knowledge on install.

---

## Auto-Discovery

Sidecar can scan your project and import knowledge automatically:

```bash
# Scan README, ADRs, config files, and detect tech stack
sidecar onboard

# Import from specific files
sidecar import docs/decisions/
sidecar import README.md
```

---

## How It Works

Sidecar stores knowledge in a local SQLite database (`.sidecar/db.sqlite`) with optional semantic embeddings for better search. Each item has:

- **Content** — the knowledge itself, in natural language
- **Type** — `decision`, `constraint`, `lesson`, or `relationship`
- **Domain** — auto-detected or manual (e.g., `backend`, `frontend`, `security`)
- **Tags** — for targeted retrieval
- **Phase** — minimum project phase for the item to activate
- **Confidence** — `1.0` for manual items, `0.7` for auto-captured

Search uses hybrid retrieval: TF-IDF keyword scoring combined with semantic similarity (when `sentence-transformers` is installed). Items are ranked by relevance and filtered by the current project phase.

---

## Development

```bash
# Install dev dependencies
pip install -e '.[dev]'
# or with uv
uv pip install -e '.[dev]'

# Run tests
uv run pytest tests/test_v3_*.py

# Lint and format
ruff check --fix src/sidecar/v3/ && ruff format src/sidecar/v3/
```

### Project layout

```
src/sidecar/v3/
  cli.py          # Click CLI commands
  knowledge.py    # Core learn/recall/conflict logic
  db.py           # SQLite storage layer
  retrieval.py    # Hybrid search (TF-IDF + semantic)
  compiler.py     # Knowledge → document compilation
  hooks.py        # Claude Code hook integration
  importer.py     # Markdown/ADR/config file importers
  audit.py        # Phase transition audit checks
  recipes.py      # Recipe system
  recipes/        # Built-in preset recipes (YAML)
  onboarding.py   # Project auto-discovery
  ecosystem.py    # AI tool recommendations

tests/
  test_v3_*.py    # All tests (380+)
```

Dependencies: `click`, `pyyaml`, `rich`. Optional: `sentence-transformers` for semantic search.

---

## License

MIT
