Collective problem-solving memory for coding agents
Local-first by default — SQLite + sqlite-vec. No daemon. No Docker.

Quick Start • How It Works • Comparison • CLI • Architecture • Development

Context7 gives your agent the docs. Context8 gives it what the docs don't cover.

Every time a coding agent solves an uncommon error, the solution vanishes after the session. Context8 stores those solutions in a vector database so any agent — yours or your team's — can find them next time.

Agent hits error → searches Context8 → finds a past solution → applies it
                                            ↓
                     Agent solves new error → logs it to Context8 → future agents benefit

That's it — no Docker, no daemon, no separate database to install.

# 1. Install Context8
pip install context8

# 2. Initialize the local DB and seed with 23 curated problem-solution pairs
context8 init --seed

# 3. Wire up your coding agent (pick one)
context8 add claude-code   # Claude Code
context8 add cursor        # Cursor
context8 add windsurf      # Windsurf

# 4. Verify everything works
context8 doctor

Restart your agent. It now has these MCP tools: context8_search, context8_log, context8_rate, context8_search_solutions, context8_stats.

The DB lives at ~/.context8/context8.db — a single SQLite file with three named vector spaces (problem, solution, code_context) backed by sqlite-vec and an FTS5 BM25 index for keyword search.

The original hackathon submission used Actian VectorAI DB over gRPC. That stack is still supported as an optional backend. The Actian SDK isn't on PyPI, so install the GitHub wheel directly alongside context8:

pip install context8 \
  "actian-vectorai @ https://github.com/hackmamba-io/actian-vectorAI-db-beta/raw/main/actian_vectorai-0.1.0b2-py3-none-any.whl"

docker compose up -d                       # starts the Actian container
CONTEXT8_BACKEND=actian context8 init --seed
CONTEXT8_BACKEND=actian context8 doctor

Set CONTEXT8_BACKEND=actian (or leave unset for the default sqlite). The same MCP tools, search semantics, and CLI commands work across both backends.

Why two install lines? PyPI doesn't allow published packages to declare URL-pinned dependencies, so we can't ship an [actian] extra that pulls the wheel automatically. Once the SDK lands on PyPI, this collapses to a single pip install context8[actian].

Coding agents have multiple ways to get help. Here's where each one fits and where it falls short:

Context7:  "Here's what the library author wrote in the docs"
Skills:    "Here's what a human wrote as a rule for this project"
Context8:  "Here's what an agent actually did to fix this exact problem last Tuesday"

Context7 is a librarian — it finds the official answer. Skills are a style guide — they enforce conventions. Context8 is a colleague — it remembers what worked in practice.

They're complementary. Use all three:

Agent encounters error
  ├── Check Skills/CLAUDE.md → "Do we have a rule for this?" (instant, project-specific)
  ├── Search Context7 → "What do the docs say?" (official, broad coverage)
  └── Search Context8 → "Has any agent solved this before?" (practical, battle-tested)

Context8 is an MCP server backed by SQLite + sqlite-vec by default (Actian VectorAI DB optional). When your agent encounters an error:

1. Search — Agent calls context8_search("TypeError Cannot read properties of undefined map React Suspense")
2. Match — Context8 runs hybrid search: dense semantic vectors find meaning-similar problems, sparse keyword vectors catch exact error tokens, metadata filters narrow by language/framework
3. Return — Agent gets ranked solutions with code diffs, confidence scores, and context
4. Learn — After solving a new problem, the agent calls context8_log(problem=..., solution=...) to store it

Results are fused with Reciprocal Rank Fusion (RRF) and filtered by language, framework, and more. The QueryAnalyzer auto-detects query type and adjusts fusion weights:

Once connected, your agent has access to:

Search for past solutions to a problem.

Input:  query (required), code_context, language, framework, limit
Output: Ranked solutions with problem, fix, code diff, confidence, tags

Log a resolved problem for future agents.

Input:  problem (required), solution (required), error_type, code_snippet,
        code_diff, stack_trace, language, framework, libraries, tags, confidence
Output: Confirmation + record ID (or duplicate detection)

Knowledge base health check.

Input:  (none)
Output: Record count, collection status, vector spaces, endpoint

context8 init                   # Create the local DB (no daemon)
context8 init --seed            # Create + seed with starter data
context8 init --seed --force    # Drop, recreate, and reseed
context8 start                  # No-op for SQLite; starts container under [actian]
context8 stop                   # No-op for SQLite; stops container under [actian]

context8 add claude             # Add to Claude Code (~/.claude/settings.json)
context8 add claude-project     # Add to project-level Claude config
context8 add cursor             # Add to Cursor (.cursor/mcp.json)
context8 add windsurf           # Add to Windsurf (.windsurf/mcp.json)
context8 remove claude          # Remove from Claude Code

context8 stats                          # Show knowledge base statistics
context8 doctor                         # Full health check (verifies named/sparse/hybrid/filter)
context8 search "query"                 # Search from the command line, with attribution
context8 search "query" -l python       # Search with language filter
context8 bench                          # Run retrieval benchmark, print Recall@K table
context8 demo                           # Scripted live demo of all advanced features
context8 import-github vercel/next.js   # Pull resolved issues from a GitHub repo
context8 serve                          # Start MCP server (agents call this automatically)

Five capabilities that turn the basic "MCP + vector DB" pattern into a production-grade framework:

Beyond the 24-record curated seed, Context8 ships an importer that pulls resolved issues straight from GitHub:

context8 import-github vercel/next.js --label bug --max-issues 50
context8 import-github fastapi/fastapi --max-issues 30
context8 import-github huggingface/transformers --label bug --max-issues 30

The importer scans the closing comments for resolution markers (fixed in, the fix is, workaround: …), extracts language/framework/error-type signals from labels and repo names, and stores everything as Context8 records. One command, hundreds of real production fixes in your DB.

Context8 is bidirectional. After an agent applies a retrieved fix, it calls context8_rate(record_id, worked=True). The record's worked_count/applied_count updates and feeds straight into the ranker — solutions that consistently work float to the top, ones that fail sink. This is the closed feedback loop that turns a static knowledge base into a self-improving one.

Every search result tells you exactly which Actian strategy surfaced it and at what rank:

Result 1 — score: 0.812 (raw: 0.945) — confidence: 95%
  via: keywords@1 (0.95) + problem@2 (0.78) + code_context@4 (0.61)
  boosts: confidence 1.00  recency 0.94  worked_ratio 0.92
  feedback: 7/8 worked (88%)

You can see the dense vector contributed less than the sparse keyword match, the recency factor barely penalized this record, and 8 prior agents have used this fix with 7 successes. The MCP tool returns the same attribution so agents can reason about result quality.

Final score = retrieval × confidence_factor × recency_factor × worked_ratio_factor. Each multiplier has a configurable floor (so a 0-confidence record loses at most 30%, never gets zeroed out), and feedback only kicks in once a record has been applied at least 3 times — preventing single bad ratings from sinking new solutions.

context8 bench ablates one Actian feature at a time over 27 ground-truth queries and prints a side-by-side table with green deltas. context8 demo runs four scripted scenarios (named vectors / hybrid fusion / filtered search / quality ranker) — designed as the script for a submission video.

┌─────────────────────────────────────────────────────────────┐
│              Coding Agent (Claude Code / Cursor / Windsurf)  │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP (stdio)
┌──────────────────────────▼──────────────────────────────────┐
│                   Context8 MCP Server                        │
│                                                              │
│  ┌────────────────┐  ┌───────────────┐  ┌────────────────┐  │
│  │   Embedding    │  │    Search     │  │ StorageService │  │
│  │   Pipeline     │  │    Engine     │  │   (facade)     │  │
│  │                │  │               │  │                │  │
│  │  MiniLM 384d   │  │  Dense+Sparse │  │  Pluggable     │  │
│  │  CodeBERT 768d │  │  RRF (Python) │  │  Backend       │  │
│  │  (opt-in)      │  │  QueryAnalyze │  │  Protocol      │  │
│  └────────────────┘  └───────────────┘  └────────┬───────┘  │
└────────────────────────────────────────────────────┼────────┘
                                                    │
        ┌───────────────────────┬───────────────────┘
        │                       │
        ▼ default               ▼ opt-in (CONTEXT8_BACKEND=actian)
┌─────────────────────────┐   ┌─────────────────────────┐
│  SQLiteBackend          │   │  ActianBackend          │
│  ~/.context8/context8.db│   │  Docker container :50051│
│                         │   │  (gRPC)                 │
│  • vec_problem  vec0    │   │  Collection:            │
│  • vec_solution vec0    │   │   context8_store        │
│  • vec_code_context vec0│   │  Named Vectors:         │
│  • fts_records (FTS5)   │   │   • problem  384d       │
│  • records (SQL + JSON1)│   │   • solution 384d       │
│  • WAL mode             │   │   • code_ctx 384/768d   │
│                         │   │  Sparse: keywords       │
└─────────────────────────┘   └─────────────────────────┘

The same three capabilities work across both backends — only the underlying mechanism differs.

The benchmark ablates one feature at a time over a 27-query ground-truth set and prints a side-by-side comparison:

context8 init --seed
context8 bench

The output table shows Recall@1, Recall@3, Recall@5, MRR, and p50 latency for four configurations — dense only → + named vectors → + hybrid fusion → + filtered search — with green deltas vs the baseline. Each row turns on one more retrieval feature. The deltas are the proof.

Run it under either backend:

context8 bench                          # SQLite (default)
CONTEXT8_BACKEND=actian context8 bench  # Actian

A live, scripted three-scenario walkthrough designed as the script for a submission video:

context8 demo

1. Named vectors — the same record retrieved three ways: by error text, by code pattern, by solution approach. One record, three independent vector spaces.
2. Hybrid fusion — ERESOLVE unable to resolve dependency tree on dense-only vs. dense + sparse RRF, side by side.
3. Filtered search — same query, language filter flipped between python and javascript, results swap server-side via FilterBuilder.

The health check asserts the three features are actually live — no silent degradation:

sqlite-vec                ✓  0.1.9
Backend connectivity      ✓  SQLite + sqlite-vec @ ~/.context8/context8.db
Schema                    ✓  records table present (23 rows)
Named vectors (3)         ✓  3 found: code_context, problem, solution
Sparse (FTS5)             ✓  fts_records virtual table present
Hybrid fusion ready       ✓  dense + sparse + RRF available
WAL mode                  ✓  journal_mode=wal
Filtered scroll           ✓  returned N record(s)

Context8 ships with 23 curated problem-solution pairs to solve the cold start problem:

Run context8 init --seed to load them. Your agents start finding solutions immediately.

# Clone and set up
git clone https://github.com/hallelx2/context8.git
cd context8
uv venv && source .venv/bin/activate  # or: .venv\Scripts\activate on Windows

# Install context8 with dev dependencies (SQLite backend works out of the box)
uv pip install -e ".[all]"

# Initialise the local DB and verify
context8 init
context8 doctor

# Run the full test suite (~125 tests, all run against SQLite, no infrastructure)
pytest tests/ -v

# Run the legacy Actian e2e suite — install the GitHub wheel and start the container first:
uv pip install "actian-vectorai @ https://github.com/hackmamba-io/actian-vectorAI-db-beta/raw/main/actian_vectorai-0.1.0b2-py3-none-any.whl"
docker compose up -d
CONTEXT8_BACKEND=actian pytest tests/ -v

# Lint + format
ruff check src/ tests/
ruff format src/ tests/

context8/
├── src/context8/
│   ├── __init__.py
│   ├── __main__.py
│   ├── config.py             # Constants, env-driven backend resolution, paths
│   ├── models.py             # ResolutionRecord, FeedbackStats, Attribution, SearchResult
│   ├── storage/              # Pluggable storage package (NEW)
│   │   ├── backend.py        # StorageBackend Protocol + SearchFilter + ScoredHit
│   │   ├── sqlite_schema.py  # DDL + apply_migrations + dim guard
│   │   ├── sqlite_backend.py # SQLite + sqlite-vec + FTS5 (default backend)
│   │   ├── actian_backend.py # Legacy Actian VectorAI DB backend
│   │   └── service.py        # StorageService env-driven facade
│   ├── agents.py             # Editor MCP config writer (Claude/Cursor/Windsurf)
│   ├── feedback.py           # FeedbackService — agent rate-this-fix loop
│   ├── embeddings/
│   │   ├── service.py        # MiniLM + CodeBERT lazy loaders
│   │   └── tokenizer.py      # BM25 tokenizer (used by ActianBackend.search_sparse)
│   ├── search/
│   │   ├── engine.py         # Backend-agnostic hybrid search + ablation flags
│   │   ├── fusion.py         # Pure-Python Reciprocal Rank Fusion (NEW)
│   │   ├── analyzer.py       # QueryAnalyzer (per-query weight tuning)
│   │   ├── ranking.py        # Confidence + recency + worked-ratio booster
│   │   └── attribution.py    # Per-strategy score tracking (backend-agnostic)
│   ├── ingest/
│   │   ├── pipeline.py       # Generic ingest pipeline
│   │   ├── seed.py           # 23 curated problem-solution starter records
│   │   └── github.py         # GitHub Issues importer (pull resolved bugs)
│   ├── benchmark/
│   │   ├── ground_truth.py   # 27 query→record evaluation pairs
│   │   └── runner.py         # Recall@K / MRR / latency evaluator
│   ├── docker.py             # Container helpers (Actian only — no-ops on SQLite)
│   ├── mcp/
│   │   ├── server.py         # MCP server entry point
│   │   └── tools.py          # 5 MCP tools (search/log/rate/search_solutions/stats)
│   └── cli/
│       ├── main.py           # Click group entry
│       ├── ui.py             # Rich helpers + backend-aware health checks
│       └── commands/
│           ├── lifecycle.py  # start / stop / init (backend-aware)
│           ├── ops.py        # stats / doctor / search / browse / export / import
│           ├── integrations.py  # add / remove (editor configs)
│           ├── bench.py      # bench / demo
│           ├── ingest.py     # import-github / mine
│           └── serve.py      # serve (MCP, backend-aware bootstrap)
├── tests/                    # ~127 unit tests (SQLite default) + Actian e2e (gated)
├── docs/                     # Architecture + build plans (hackathon-era)
├── .github/workflows/        # CI + PyPI release
├── docker-compose.yml        # Actian container — only used under [actian]
├── pyproject.toml
├── RESULTS.md                # Submission deliverable: bench numbers + narrative
└── CLAUDE.md

# Bump version in pyproject.toml and src/context8/__init__.py, add a
# changelog entry, then:
git tag v1.0.0
git push --tags
# CI runs → PyPI publishes → GitHub Release created automatically

Post-v1, follow semver: bump the patch for fixes, the minor for additive features (e.g. a new backend), and the major only for breaking changes to the surface listed in the v1.0.0 changelog entry.

The version jump from 0.x to 1.0 marks two things: (1) the default install is finally a one-command pip install context8 with no non-PyPI wheels, and (2) the public surface — MCP tools, CLI command names, env-var conventions, and the StorageBackend Protocol — is now committed to under semver. Future backend additions (e.g. Postgres + pgvector for a hosted version) will be additive third Protocol implementations, not breaking changes.

Public API surface guaranteed under semver:

• MCP tools: context8_search, context8_log, context8_rate, context8_search_solutions, context8_stats.
• CLI commands: init, start, stop, doctor, stats, search, browse, add, remove, bench, demo, serve, export, import, import-github, mine.
• Env vars: CONTEXT8_BACKEND, CONTEXT8_DB_PATH, CONTEXT8_DB_HOST, CONTEXT8_DB_PORT, CONTEXT8_USE_CODE_MODEL, CONTEXT8_TEXT_MODEL, CONTEXT8_CODE_MODEL, CONTEXT8_RECENCY_HALF_LIFE_DAYS.
• Backend Protocol: StorageBackend and the SearchFilter / ScoredHit dataclasses in context8.storage.
• JSON export format (format: "context8-export", version: 1) — backend-agnostic, used for cross-backend migration.

What changed in this release (full rollup from 0.4.0):

• Pluggable storage backends. SQLite + sqlite-vec + FTS5 is the new default — no Docker, no daemon, single-file DB at ~/.context8/context8.db.
• Backward-compatible Actian backend. Install the SDK wheel from GitHub alongside context8 and set CONTEXT8_BACKEND=actian to keep using the original hackathon stack. (PyPI doesn't allow URL-pinned extras, so the install is two lines instead of one.)
• Search engine refactor. search/engine.py no longer imports a vendor SDK; it talks to a StorageBackend Protocol. RRF moved to search/fusion.py as pure Python.
• Backend-aware CLI. start/stop print "no daemon needed" under SQLite; init runs schema migrations; doctor checks file integrity, WAL mode, vec0 + FTS5 modules.
• Concurrency. WAL mode + 5s busy timeout for parallel MCP reads while ingest writes.
• vec0 dim guard. Flipping CONTEXT8_USE_CODE_MODEL after init fails loudly with a --force hint instead of silently corrupting the DB.
• New tests. tests/test_storage_sqlite.py (18 unit tests), tests/test_e2e_sqlite.py (full e2e on SQLite), tests/test_search_filter.py (filter translation). 127 tests pass on a fresh checkout, 15 Actian-only tests skip cleanly without CONTEXT8_BACKEND=actian.
• Fixed pre-existing test bug. FeedbackService(storage, embeddings) arity mismatch in test_e2e.py:281,300.

Migration from 0.4.x:

# If you had data in the Actian backend:
CONTEXT8_BACKEND=actian context8 export -o backup.json
pip install -U context8                    # pulls v1.0.0
context8 init                              # creates fresh SQLite DB
context8 import backup.json                # re-embeds and imports

If you want to keep using Actian: pip install -U context8 "actian-vectorai @ https://github.com/hackmamba-io/actian-vectorAI-db-beta/raw/main/actian_vectorai-0.1.0b2-py3-none-any.whl" and set CONTEXT8_BACKEND=actian. No other changes required.

• Container runtime: Docker + Podman auto-detection with cached probing
• Self-bootstrapping serve: context8 serve now starts DB, inits collection, and caches models before the MCP loop — works on a cold machine with zero prior setup
• --no-bootstrap flag: skip auto-bootstrap if you manage infra manually
• Hybrid search restored: sparse vector detection now reads collection info on every startup instead of defaulting to False
• Sparse search fix: passes SparseVector object with using="keywords" (was rejected by server)
• Async MCP fix: tool calls wrapped in asyncio.to_thread — no more event loop blocking
• Browse resource leak fix: gRPC client always closed on no-results path
• Embedding cache fix: hash full text, not just first 500 chars
• Configurable dims: TEXT_EMBED_DIM / CODE_EMBED_DIM flow through everywhere
• CodeBERT env var: CONTEXT8_USE_CODE_MODEL=1 enables 768d code embeddings
• Browse + ecosystem MCP tools: metadata filtering and stack-based discovery for skill writing
• Auto-capture + auto-suggest hooks: Claude Code hooks for zero-effort logging and retrieval
• Session mining: context8 mine ~/.claude/sessions/
• Export/import: context8 export -o backup.json / context8 import backup.json
• Solution versioning: same problem, different fix stored as variants
• Batch ingest: ~20x faster for GitHub imports and seeding
• Claude Code plugin install: context8 add claude writes to plugin directory, not settings.json

• Auto-start Docker, pre-download models, one-stop context8 init
• Docker compose generated in ~/.context8/ for pip-installed users
• Agent config for 6 agents: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini

• Framework restructure into subpackages
• GitHub Issues importer, feedback loop, quality ranker, per-strategy attribution
• Benchmark suite with Recall@K ablation
• 79 unit tests

• Initial release: MCP server, hybrid search, 24 seed records, CLI

MIT

Originally built for the Actian VectorAI DB Build Challenge. Now SQLite-first; Actian remains a supported optional backend.