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.

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

# 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

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

# 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

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

Generate documents

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

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

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.

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:

# 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

# 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