context8 0.4.0

Collective problem-solving memory for coding agents — powered by Actian VectorAI DB

Context8

Collective problem-solving memory for coding agents
Powered by Actian VectorAI DB

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

---

Prerequisites

Requirement	Why
Docker Desktop	Runs the Actian VectorAI DB container locally
Python 3.10+	Runs the Context8 CLI and MCP server

Quick Start

# 1. Install context8 + the Actian VectorAI DB client
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"

# Or with uv
uv 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"

# 2. Start the database (pulls and runs the Docker container)
context8 start

# 3. Initialize and seed with 24 curated problem-solution pairs
context8 init --seed

# 4. Add to your coding agent (pick one)
context8 add claude       # Claude Code
context8 add cursor       # Cursor
context8 add windsurf     # Windsurf

# 5. Verify everything works
context8 doctor

Restart your agent. It now has three new tools: context8_search, context8_log, and context8_stats.

Why two packages? The actian-vectorai SDK is distributed by Actian as a beta wheel and is not yet on PyPI. Context8 is on PyPI. Once Actian publishes their SDK to PyPI, this becomes a single pip install context8.

---

Context8 vs Context7 vs Skills

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

The Context Layers

Layer	Source	What It Covers	Limits
Context 1–6	Codebase, conversation, memory	Your current project's files and history	Only knows your code
Context7	Official documentation (Upstash)	API references, common usage patterns, getting-started guides	Only covers documented knowledge
Skills / CLAUDE.md	Hand-written rules	Project conventions, tool-specific patterns, coding style	Manual maintenance, doesn't learn
Context8	Agent problem-solving history (Actian VectorAI DB)	Uncommon errors, workarounds, integration bugs, agent-discovered fixes	Needs seeding and accumulation

When Each One Helps (and When It Doesn't)

Scenario	Context7 (Docs)	Skills / Rules	Context8 (Memory)
"How do I use the useQuery hook?"	Best fit — it's in the React Query docs	Partial — if someone wrote a skill for it	Overkill — docs cover this
"What's our team's folder naming convention?"	Won't help — not in public docs	Best fit — written in CLAUDE.md	Won't help — not a problem/solution
ERESOLVE unable to resolve dependency tree after upgrading npm	Partial — npm docs mention peer deps vaguely	Won't help — too specific	Best fit — exact error with proven fix
Hydration mismatch in Next.js 15 + React 19 RC	Outdated — docs haven't caught up	Won't help	Best fit — another agent hit this last week
torch.cuda.OutOfMemoryError during fine-tuning even with batch_size=1	Partial — PyTorch docs cover CUDA basics	Won't help	Best fit — solution with 4 ranked fix strategies
docker compose volume empty on Windows WSL2	Won't help — Docker docs assume Linux	Maybe — if someone added a WSL tip	Best fit — exact OS-specific workaround

The Key Difference

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)

---

How It Works

Context8 is an MCP server backed by Actian VectorAI DB. 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

Three Search Strategies, Fused Together

Strategy	Vector Space	What It Catches	Example
Dense search	problem (384d, MiniLM)	Semantic meaning	"undefined array access" matches "null reference on collection"
Dense search	code_context (768d, CodeBERT)	Code patterns	data?.items ?? [] matches optional chaining null safety
Sparse search	keywords (BM25)	Exact tokens	ModuleNotFoundError matches ModuleNotFoundError exactly

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:

Query Type	Dense Weight	Code Weight	Sparse Weight
Error message (TypeError: ...)	0.40	0.15	0.45
Error + code context	0.35	0.30	0.35
Code snippet only	0.25	0.55	0.20
Natural language question	0.60	0.15	0.25

---

MCP Tools

Once connected, your agent has access to:

context8_search

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

context8_log

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)

context8_stats

Knowledge base health check.

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

---

CLI Reference

Setup

context8 start                  # Start the Actian VectorAI DB container
context8 stop                   # Stop the container
context8 init                   # Create the collection
context8 init --seed            # Create + seed with starter data
context8 init --seed --force    # Drop, recreate, and reseed

Agent Integration

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

Operations

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)

---

What's in the box

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

1. Real-world ingestion at scale

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.

2. Agent feedback loop (context8_rate)

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.

3. Per-strategy attribution

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.

4. Quality ranker (search/ranking.py)

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.

5. Evaluation as a first-class artifact

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.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│              Coding Agent (Claude Code / Cursor / Windsurf)  │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP (stdio)
┌──────────────────────────▼──────────────────────────────────┐
│                   Context8 MCP Server                        │
│                                                              │
│  ┌────────────────┐  ┌───────────────┐  ┌────────────────┐  │
│  │   Embedding    │  │    Search     │  │    Storage     │  │
│  │   Pipeline     │  │    Engine     │  │    Service     │  │
│  │                │  │               │  │                │  │
│  │  MiniLM 384d   │  │  Dense+Sparse │  │  Named Vecs   │  │
│  │  CodeBERT 768d │  │  RRF Fusion   │  │  Filters      │  │
│  │  BM25 Sparse   │  │  QueryAnalyze │  │  Dedup        │  │
│  └────────────────┘  └───────────────┘  └────────────────┘  │
└──────────────────────────┬──────────────────────────────────┘
                           │ gRPC :50051
                ┌──────────▼──────────┐
                │  Actian VectorAI DB │
                │  (Docker Container) │
                │                     │
                │  Collection:        │
                │   context8_store    │
                │                     │
                │  Named Vectors:     │
                │   • problem  384d   │
                │   • solution 384d   │
                │   • code_ctx 768d   │
                │  Sparse: keywords   │
                │  Payload: metadata  │
                └─────────────────────┘

---

Hackathon: Advanced Features Used

Built for the Actian VectorAI DB Build Challenge

This project uses all three advanced features required by the hackathon — and ships a benchmark that proves each one is load-bearing, not decorative.

Feature	How Context8 Uses It	Why It Matters
Hybrid Fusion	Dense semantic + sparse BM25 keyword vectors, fused with RRF	Error messages contain both meaning and exact tokens — you need both
Filtered Search	Metadata filters by language, framework, error type, resolution status	A Python agent doesn't need TypeScript solutions
Named Vectors	3 separate spaces: problem (384d), solution (384d), code_context (768d) — all three queried at runtime	Error descriptions, fix descriptions, and code are semantically different domains

Prove it: context8 bench

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 Actian feature. The deltas are the proof.

See it: context8 demo

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.

Verify it: context8 doctor

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

Named vectors (≥3)        ✓  3 found: code_context, problem, solution
Sparse vectors            ✓  enabled: keywords
Hybrid fusion ready       ✓  dense + sparse + RRF fusion available
Filtered search           ✓  FilterBuilder query succeeded

---

Tech Stack

Component	Technology	Purpose
Vector Database	Actian VectorAI DB	Storage, indexing, HNSW search
Dense Embeddings	sentence-transformers/all-MiniLM-L6-v2	384d text vectors (problems, solutions)
Code Embeddings	microsoft/codebert-base	768d code-aware vectors (opt-in)
Sparse Embeddings	Custom BM25 tokenizer	Exact keyword matching
MCP Server	Python mcp SDK	stdio transport to agents
CLI	Click + Rich	Terminal UX with tables, panels, health checks
CI/CD	GitHub Actions	Lint → Test → Build → Publish to PyPI
Package	uv / pip / hatchling	PEP 517 compatible

---

Seed Data

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

Category	Count	Examples
Python environment	5	venv conflicts, PEP 668, asyncio in Jupyter, CUDA OOM
Node.js / npm	3	peer deps, ESM vs CJS, heap out of memory
React / Next.js	3	hydration mismatch, setState in render, streaming API routes
TypeScript	2	type narrowing to never, path alias resolution
Docker	2	volume mounts on WSL2, port conflicts
Database	1	connection pool exhaustion in serverless
Git	1	lockfile merge conflicts
Rust	2	WASM no_std, borrow checker in loops
AI / ML	2	OpenAI rate limits, HuggingFace generation issues
Build tools	1	Vite prebundling cache
Cross-platform	1	Windows long path ENOENT

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

---

Development

# 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 + dev deps + actian client
uv pip install -e ".[all]" "actian-vectorai @ https://github.com/hackmamba-io/actian-vectorAI-db-beta/raw/main/actian_vectorai-0.1.0b2-py3-none-any.whl"

# Start the DB and verify
context8 start
context8 doctor

# Run tests (29 unit tests, no DB needed)
pytest tests/ -v

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

Project Structure

context8/
├── src/context8/
│   ├── __init__.py
│   ├── __main__.py
│   ├── config.py             # Constants, paths, agent registry, ranker tuning
│   ├── models.py             # ResolutionRecord, FeedbackStats, Attribution, SearchResult
│   ├── storage.py            # Actian VectorAI DB client (named + sparse fallback)
│   ├── 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 sparse tokenizer
│   ├── search/
│   │   ├── engine.py         # Hybrid search with ablation flags
│   │   ├── analyzer.py       # QueryAnalyzer (per-query weight tuning)
│   │   ├── ranking.py        # Confidence + recency + worked-ratio booster
│   │   └── attribution.py    # Per-strategy score tracking
│   ├── ingest/
│   │   ├── pipeline.py       # Generic ingest pipeline
│   │   ├── seed.py           # 24 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
│   ├── 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 + DB connection check
│       └── commands/
│           ├── lifecycle.py  # start / stop / init
│           ├── ops.py        # stats / doctor / search
│           ├── integrations.py  # add / remove (editor configs)
│           ├── bench.py      # bench / demo
│           ├── ingest.py     # import-github
│           └── serve.py      # serve (MCP)
├── tests/                    # 79 unit tests + e2e suite
├── docs/                     # Architecture + build plans
├── .github/workflows/        # CI + PyPI release
├── docker-compose.yml
├── pyproject.toml
├── RESULTS.md                # Submission deliverable: bench numbers + narrative
└── CLAUDE.md

Releasing

# Bump version in pyproject.toml and src/context8/__init__.py, then:
git tag v0.2.0
git push --tags
# CI runs → PyPI publishes → GitHub Release created automatically

---

Changelog

v0.4.0

• 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

v0.3.0

• 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

v0.2.0

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

v0.1.0

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

License

MIT

---

_{Built with Actian VectorAI DB for the Actian VectorAI DB Build Challenge}