codevira 2.0.0__tar.gz → 2.1.1__tar.gz

{codevira-2.0.0 → codevira-2.1.1}/CHANGELOG.md

@@ -11,19 +11,66 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.1.1] — 2026-05-17 — Hybrid decision search
+
+### Added
+- **Hybrid search for `search_decisions`** (BM25 + ChromaDB semantic + RRF fusion).
+  Closes the UDAP-benchmark gap: queries like `"DDD architecture layer"` or
+  `"codevira backfill"` that returned 0 hits in v2.0/v2.1.0 now surface the
+  right decisions via semantic recall. Response includes a `retrieval` field
+  indicating which path contributed (hybrid / keyword / semantic).
+- **`codevira heal --decisions`** — non-destructive backfill embedding all
+  existing decisions into the semantic index. Run once after upgrading from
+  v2.0/v2.1.0 to pick up hybrid recall on pre-existing decision history.
+  Idempotent (upsert pattern).
+- **`mcp_server/tools/_decision_embeddings.py`** — new helper module:
+  embed_decision, semantic_search_decisions, rrf_merge, backfill_all_decisions.
+  P9 graceful degradation throughout — chromadb failures never block SQL
+  writes or BM25 reads.
+
+### Tests
+- `tests/test_decision_embeddings.py` — 15 new regression tests covering
+  RRF math, graceful-degradation paths, and the explicit benchmark queries.
+
+## [2.1.0] — 2026-05-17 — Reliability hardening + Pillar 3 discipline scaffold
+
+### Added — Pillar 3: AI development discipline scaffold (2026-05-16)
+
+The codevira repo now ships its own discipline scaffold — the same
+pattern that will be exposed as `codevira discipline install` in
+v2.2. This is the reference implementation, eaten as dog food.
+
+- **`.claude/skills/`** — 4 SKILL.md files: `development-discipline`,
+  `open-source-quality`, `release-readiness`, `epistemic-honesty`.
+- **`.claude/hooks/pre-release-block.sh`** — PreToolUse hard wall.
+  Refuses `twine upload`, `gh release ... --draft=false`,
+  `pipx publish`, etc. unless `.release-evidence/<version>.json`
+  shows G1–G5 pass. Bypass via `CODEVIRA_RELEASE_OVERRIDE=1`.
+- **`Makefile`** — 12 targets including `release-verify-version`,
+  `release-gauntlet`, `release-build`, `release-dry-run`,
+  `release-publish`, `release-smoke`, `release-full`.
+- **`.pre-commit-config.yaml`** — ruff lint+format, mypy, hygiene.
+- **`tests/e2e/test_first_contact.py`** + 4 fixtures (docs_only,
+  code_only_python, polyglot, monorepo). G2 gate.
+- **`.github/workflows/{ci,release-gate}.yml`** — CI hard wall.
+- **`codevira.discipline.yaml`** — central scaffold config.
+- **`scripts/check_real_ide_smoke.sh`** — G3 stub.
+- **`docs/release-process.md`** — step-by-step foolproof release.
+
 ### Planned for v2.1
 
-See [ROADMAP.md](ROADMAP.md#-v21--honest-known-limitations-from-the-rc5-audit-2026-05-13).
-
-- **Multi-language `get_signature` / `get_code`** — wire tree-sitter (already
-  used for graph indexing) into these tools so non-Python projects stop
-  getting "Python-only by design".
-- **`record_decisions_batch` API** — compress 50× ~800 B per-call overhead
-  into one round-trip.
-- **CLI naming clarity** — pick a canonical hierarchy among `init` / `setup` /
-  `register` / `configure`; add a `codevira inspect` umbrella; deprecate one
-  of `--project-dir` (global) / `--project PATH` (per-subcommand) on a
-  v2.1 → v2.2 cycle.
+See [ROADMAP.md](ROADMAP.md#-v21--new-user-first-contact--reliability-hardening).
+
+- **Reliability hardening (23 bugs A–O)** — silent-failure elimination
+  surfaced by the discipline-scaffold e2e fixtures.
+- **Hybrid search (BM25 + semantic + rerank)** — natural-language
+  decision search.
+- **Decision deduplication** (ADD/UPDATE/NOOP) + audit trail.
+- **Conditional hook injection** — kill the always-on token tax.
+- **Multi-language `get_signature` / `get_code`** — wire tree-sitter.
+- **`record_decisions_batch` API** — compress protocol overhead.
+- **CLI naming clarity** — `init` / `setup` / `register` / `configure`
+  canonical hierarchy.
 
 ---
 

{codevira-2.0.0/codevira.egg-info → codevira-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: codevira
-Version: 2.0.0
+Version: 2.1.1
 Summary: Stop re-explaining your project to AI agents every session. Codevira gives Claude Code, Cursor, Windsurf, and Antigravity shared persistent memory of your codebase — locally, no signup, MIT-licensed. One install configures every AI tool.
 Author-email: Sachin Shelke <sachin.worldnet@gmail.com>
 License: MIT
@@ -36,6 +36,14 @@ Requires-Dist: chromadb>=0.5.0
 Requires-Dist: sentence-transformers>=2.7.0
 Provides-Extra: search
 Provides-Extra: all
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
 
 # Codevira
 

{codevira-2.0.0 → codevira-2.1.1/codevira.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: codevira
-Version: 2.0.0
+Version: 2.1.1
 Summary: Stop re-explaining your project to AI agents every session. Codevira gives Claude Code, Cursor, Windsurf, and Antigravity shared persistent memory of your codebase — locally, no signup, MIT-licensed. One install configures every AI tool.
 Author-email: Sachin Shelke <sachin.worldnet@gmail.com>
 License: MIT
@@ -36,6 +36,14 @@ Requires-Dist: chromadb>=0.5.0
 Requires-Dist: sentence-transformers>=2.7.0
 Provides-Extra: search
 Provides-Extra: all
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-timeout>=2.1; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
 
 # Codevira
 

{codevira-2.0.0 → codevira-2.1.1}/codevira.egg-info/SOURCES.txt

@@ -29,6 +29,7 @@ codevira.egg-info/entry_points.txt
 codevira.egg-info/requires.txt
 codevira.egg-info/top_level.txt
 docs/alpha-tester-invites.md
+docs/foolproof-product-charter.md
 docs/hn-launch-day.md
 docs/how-i-built-persistent-memory-for-ai-agents.md
 docs/linkedin-article-ai-agent-memory.md
@@ -36,6 +37,7 @@ docs/linkedin-post-ai-agent-memory.md
 docs/local-pypi-https.md
 docs/medium-your-ai-coding-agent-has-amnesia.md
 docs/qa-playbook.md
+docs/release-process.md
 docs/roadmap.md
 docs/v2-completion-plan.md
 docs/v2-execution-log.md
@@ -55,6 +57,7 @@ docs/heroes/09-intent-inference.md
 docs/heroes/10-ai-promotion.md
 docs/heroes/README.md
 docs/heroes/pillar-1-setup.md
+docs/internal/competitive-landscape.md
 graph/_schema.yaml
 indexer/__init__.py
 indexer/_dedupe_migration.py
@@ -104,7 +107,6 @@ mcp_server/server.py
 mcp_server/setup_wizard.py
 mcp_server/data/__init__.py
 mcp_server/data/config.example.yaml
-mcp_server/data/__pycache__/__init__.cpython-313.pyc
 mcp_server/data/agents/builder.md
 mcp_server/data/agents/developer.md
 mcp_server/data/agents/documenter.md
@@ -160,6 +162,7 @@ mcp_server/engine/wiring/__init__.py
 mcp_server/engine/wiring/claude_code_hooks.py
 mcp_server/engine/wiring/mcp_dispatch.py
 mcp_server/tools/__init__.py
+mcp_server/tools/_decision_embeddings.py
 mcp_server/tools/changesets.py
 mcp_server/tools/code_reader.py
 mcp_server/tools/graph.py
@@ -189,6 +192,7 @@ tests/test_cli_projects.py
 tests/test_cli_replay.py
 tests/test_cli_version.py
 tests/test_crash_logger.py
+tests/test_decision_embeddings.py
 tests/test_dedupe_migration.py
 tests/test_detect.py
 tests/test_doctor.py

{codevira-2.0.0 → codevira-2.1.1}/codevira.egg-info/requires.txt

@@ -12,4 +12,13 @@ sentence-transformers>=2.7.0
 
 [all]
 
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21
+pytest-timeout>=2.1
+ruff>=0.6.0
+mypy>=1.10
+types-PyYAML
+pre-commit>=3.5
+
 [search]

codevira-2.1.1/docs/foolproof-product-charter.md

@@ -0,0 +1,197 @@
+# Codevira Foolproof Product Charter
+
+**The product, not just the release.** v2.0.0 shipped via a process
+that satisfied "all unit tests pass," but the *product* shipped with
+23 silent-failure bugs. This document defines what "foolproof
+product" means for codevira and how every code change must satisfy
+it.
+
+The release-discipline scaffold (Makefile + hook + CI + skills) is
+the process. **This charter is the product**. They're complementary;
+both are necessary.
+
+---
+
+## The 10 product principles (P1–P10)
+
+| # | Principle | One-line rule |
+|---|---|---|
+| **P1** | No silent failures | Every 0-result code path emits a reason + `fix_command`. |
+| **P2** | Self-diagnose on startup | Every entry point detects + reports known-bad states; never starts in a degraded state silently. |
+| **P3** | Atomic state mutations | All external writes (files, DB, IDE configs) use atomic patterns. No half-written state. |
+| **P4** | Defensive parsing | External input parses with fail-safe defaults; never crashes on malformed input. |
+| **P5** | Bounded resources | No unbounded loops, retries, or log writes. Circuit breakers on every retry boundary. |
+| **P6** | Predictable detection | One source of truth per concept. Two code paths that look at the same thing must agree. |
+| **P7** | Reversible operations | Every install has a documented + tested uninstall. Every write merges, never overwrites user keys. |
+| **P8** | Helpful error messages | WHAT failed + WHY + FIX. The `fix_command` pattern in every MCP tool response. |
+| **P9** | Graceful degradation | Single-subsystem failure must not cascade. Document what still works when X is broken. |
+| **P10** | Observability | Structured logging; `codevira doctor` reads actual state, never infers; logs auto-rotate. |
+
+Full SKILL definitions live in
+[`.claude/skills/foolproof-product/SKILL.md`](../.claude/skills/foolproof-product/SKILL.md).
+Machine-checkable tests live in
+[`tests/e2e/test_product_invariants.py`](../tests/e2e/test_product_invariants.py).
+
+---
+
+## How the principles map to the v2.0 bugs
+
+Every v2.0 bug traces to one or more violated P-principle. The
+post-mortem:
+
+| Bug | What broke | Violated principles |
+|---|---|---|
+| **A** — discovery vs. indexing matcher mismatch | `configure` finds 8 files; `index` matches 0 | P6 (predictable detection) |
+| **B** — `index` says "up to date" with 0 chunks | Lies about state | P1 (silent failure) |
+| **C** — `status` shows 0/0 with no warning on uninitialized | No actionable state signal | P1, P10 |
+| **D** — config split between in-repo and centralized | Two configs disagree silently | P3 (atomic), P6 |
+| **E** — docs-only repos produce silent 0 chunks | No reason given | P1 |
+| **F** — `init` drops top-level files (`.`) | Single-language filter on dirs | P6 |
+| **G** — project keys are unreadable hashes | UX-hostile state representation | (UX, not a P violation) |
+| **H** — no `--verbose` on `index` | No way to diagnose | P10 |
+| **I** — "Auto-detected" promises detection but shows defaults | Misleading label | P1, P8 |
+| **J/K** — sentence-transformers on critical path | Claude Desktop disconnects | P9 (graceful degradation) |
+| **L** — init lists generic dirs not present | False positives in detection | P1, P6 |
+| **M** — init shows all 80 extensions regardless of project | Same | P1 |
+| **N** — init interactive but should match configure | Inconsistency | P6 |
+| **O** — configure typing "1,3,5" not arrow-keys | UX (not P violation, but quality) |
+| **HNSW writer crash storm** | 41 crashes in one session | P2 (startup detect), P5 (circuit breaker) |
+| **41-crash log spam** | Grows unbounded | P5, P10 |
+| **Claude Desktop config cleared (rare)** | Race in non-atomic write | P3 |
+| **codevira clean leaves orphaned hooks** | Reverse incomplete | P7 |
+
+**Lesson:** these aren't isolated bugs. They're a category. The
+category is "we wrote code that satisfies the function signature but
+not the product invariants."
+
+---
+
+## The mandatory checklist (every code change to mcp_server/ or indexer/)
+
+```
+Subsystem touched: <indexer | MCP tool | hook | CLI | watcher>
+Files in target list: <N files>
+
+For each affected code path, answer:
+
+P1  No silent failures      [ ] All 0-result paths emit reason + fix_command
+P2  Self-diagnose           [ ] Doctor check added/updated if state added
+P3  Atomic mutations        [ ] Writes use tmp→fsync→rename or transactions
+P4  Defensive parsing       [ ] External input has try/except + safe default
+P5  Bounded resources       [ ] Loops bounded; retries have circuit breaker
+P6  Predictable detection   [ ] No parallel matcher; single source of truth
+P7  Reversible              [ ] Uninstall counterpart works (tested)
+P8  Helpful errors          [ ] Every error: WHAT + WHY + FIX
+P9  Graceful degradation    [ ] List what still works when this subsystem fails
+P10 Observability           [ ] Structured log; doctor surfaces new state
+
+Justifications for any "N/A":
+  <e.g. "P3 N/A: no external state written">
+```
+
+A code review (human OR AI) that doesn't see this checklist for a
+mcp_server/indexer change is a discipline breach. The
+`foolproof-product` SKILL.md enforces it conversationally; the
+`test_product_invariants.py` suite enforces it mechanically.
+
+---
+
+## Subsystem-specific invariants
+
+### Indexer
+- One matcher (`discover_source_files()` is THE matcher)
+- 0-chunk results MUST include reason + fix_command
+- Watcher: circuit-broken after 5 consecutive failures
+- Crash log rate-limited: 1 entry per file per minute MAX
+
+### MCP server
+- `tools/list` MUST respond in <1s (no chromadb / sentence-transformers
+  import on critical path)
+- Every tool response includes `fix_command` on error
+- Graceful degradation: keyword search works without ChromaDB
+- Startup self-check: Chroma openable, DB tables present, version OK
+
+### CLI
+- Every error message: WHAT + WHY + FIX
+- Every command has `--help` + a docstring
+- Status / doctor must reflect actual state, never lie
+
+### Hooks
+- Hook scripts MUST be idempotent (re-running is safe)
+- `hooks uninstall` removes everything `hooks install` wrote
+- Hook injection respects user keys in `~/.claude/settings.json`
+
+### IDE config writes
+- Atomic: tmp → fsync → rename
+- Merge: never overwrite user keys
+- Verify: read back after write to confirm
+
+---
+
+## Graceful degradation matrix
+
+What still works when each subsystem fails:
+
+| Down | Still works |
+|---|---|
+| **ChromaDB corrupt** | Keyword search via SQLite, decisions, graph, roadmap, changesets |
+| **HuggingFace network down** | Cached model continues to work |
+| **`~/.codevira/global.db` corrupt** | Auto-reinit + warn; per-project state preserved |
+| **Watcher crash** | All MCP tools; manual `codevira index --full` available |
+| **One hook script broken** | MCP server alone; other hooks continue |
+| **Disk full** | Operations refuse with clear "disk full" message; never silently truncate |
+| **Permission denied** | Clear error with `chmod` / `chown` remediation |
+
+Every new feature: ask "if this fails, what continues to work?"
+Document the answer in the docstring AND in the relevant cell of
+this matrix.
+
+---
+
+## The continuous-foolproof loop
+
+```
+1. Bug found in production
+       ↓
+2. Identify which P-principle was violated
+       ↓
+3. Fix the bug
+       ↓
+4. Add a regression test to test_first_contact.py OR test_product_invariants.py
+       ↓
+5. If the test exposes a pattern (not just one bug), strengthen the
+   relevant P principle in the SKILL.md
+       ↓
+6. Update this charter's bug table (the post-mortem section above)
+```
+
+Goal: every category of bug we ship gets encoded as a principle.
+The next bug in that category fails the gauntlet before reaching users.
+
+---
+
+## Anti-patterns the charter forbids
+
+These are non-negotiable. A PR that introduces any of these is
+blocked at review:
+
+1. **Returning 0 results without a reason field.**
+2. **Catching exceptions and silently continuing without logging.**
+3. **Retry loops without a max-iteration limit.**
+4. **Error messages that say "failed" without saying WHY.**
+5. **New subsystems without a `codevira doctor` check.**
+6. **New subsystems without a clean uninstall path.**
+7. **Writes that overwrite user keys in shared config files.**
+8. **DB migrations without a rollback script.**
+9. **"It works in the happy path" without walking the sad paths.**
+10. **Skipping P1-P10 checklist with "looks fine."**
+
+---
+
+## Reference
+
+- Skill enforcement: [`.claude/skills/foolproof-product/SKILL.md`](../.claude/skills/foolproof-product/SKILL.md)
+- Machine tests: [`tests/e2e/test_product_invariants.py`](../tests/e2e/test_product_invariants.py)
+- Bug catalog: [ROADMAP.md § v2.1](../ROADMAP.md#-v21--new-user-first-contact--reliability-hardening)
+- Release process: [`docs/release-process.md`](release-process.md)
+- Contributor guide: [`CONTRIBUTING.md`](../CONTRIBUTING.md)

codevira-2.1.1/docs/internal/competitive-landscape.md

@@ -0,0 +1,239 @@
+# Competitive Landscape — Internal
+
+> **NOT PUBLIC.** This file is in `.gitignore`. Never commit, never link
+> from public docs, never reference by name in marketing copy. Used to
+> drive internal v2.x prioritization.
+
+**Last updated:** 2026-05-15
+**Refresh cadence:** quarterly, or whenever a major competitor ships
+something significant.
+
+---
+
+## Why this is private
+
+The public `ROADMAP.md` is vision-led — capabilities framed by what
+they do for codevira's users. This doc is intelligence-led —
+capabilities framed by what competitors offer. The two should never
+be merged: naming competitors in your own roadmap reads as reactive
+follower-positioning. Keep this conversation internal.
+
+Each public roadmap item maps back to one or more competitive gaps
+listed here. Engineering knows the strategic intent without the
+roadmap telegraphing our moves.
+
+---
+
+## mem0 (https://mem0.ai)
+
+**Positioning:** the default conversational-memory layer for
+general-purpose AI agents and chatbots. Optimized for fast
+extraction-and-distillation of natural-language facts at scale across
+20+ vector stores.
+
+**Mindshare:** ~55.7K GitHub stars, ~90K developer install base,
+$19–249/mo cloud tiers, 114 open issues.
+
+**Recent moves (Feb–May 2026):**
+- May 13 — Memory Decay (recency-aware ranking)
+- May 12 — Temporal Reasoning launch
+- April — new memory algorithm with +20–27pt benchmark gains
+- April 17 — security disclosure (CVSS 8.1)
+- March 24 — official `mem0-mcp` archived; pivoted to hosted
+  `mcp.mem0.ai` (Platform-only)
+- Recent — `graph_store` removed from OSS, replaced by in-vector-store
+  entity linking
+
+### mem0 capability matrix
+
+| Capability | mem0 | codevira | Verdict | v2.x slot |
+|---|---|---|---|---|
+| `add` / `search` / `get` / `update` / `delete` | ✅ | ✅ (different naming) | parity | — |
+| Hybrid search (BM25 + semantic) | ✅ | ❌ keyword only | **MUST CLOSE** | v2.1 — "natural-language decision search" |
+| Re-ranking (Cohere, cross-encoder, LLM) | ✅ | ❌ | **MUST CLOSE** | v2.2 — "reranker integration" |
+| ADD/UPDATE/DELETE/NOOP auto-decisioning | ✅ | ❌ append-only | **MUST CLOSE** | v2.1 — "decision deduplication" |
+| Memory history per ID | ✅ | ❌ timestamps only | **MUST CLOSE** | v2.1 — "decision audit trail" |
+| Feedback API (quality signals) | ✅ | ❌ | should close | v2.2 — "memory feedback API" |
+| Batch ops (bulk update/delete) | ✅ | ❌ | should close | v2.2 — "batch ops" |
+| Compound filter V2 (AND/OR on metadata) | ✅ Platform | partial | should close | v2.2 |
+| Memory decay (recency ranking) | ✅ Platform | ❌ | nice to have | v2.2 if time |
+| Temporal reasoning (point-in-time queries) | ✅ Platform | ❌ | nice to have | v2.3+ |
+| Multi-vector-store adapters | ✅ 20+ | ❌ Chroma only | partial | v2.2 — pick top 3 (Pinecone/Qdrant/pgvector) |
+| Memory compression (auto-condense) | ✅ | ❌ | nice to have | v2.3+ |
+| JavaScript/Node SDK | ✅ | ❌ MCP only | **MUST CLOSE** | v2.2 — "Node SDK + Vercel AI SDK" |
+| REST API (publicly addressable) | ✅ | partial (HTTP, not REST-shaped) | should close | v2.2 — "REST API surface" |
+| Webhooks | ✅ | ❌ | nice to have | defer |
+| LangChain / LlamaIndex / CrewAI / AutoGen adapters | ✅ | ❌ | should close | v2.2 — "framework adapters" |
+| Multimodal (PDF, images) | ✅ Platform | ❌ | don't chase | — |
+| Group chat / shared memory | ✅ Platform | ❌ | defer to cloud tier | v2.3 (cloud) |
+| Custom categories / taxonomy | ✅ Platform | partial (decisions/preferences/rules) | don't chase | — |
+| SSO / audit logs / SOC2 | ✅ Pro+ | ❌ | enterprise-only | defer |
+
+### Codevira's structural moats vs mem0
+
+**These are things mem0 cannot copy without abandoning their core.
+Never give them up chasing parity items.**
+
+| Capability | Why it's a moat |
+|---|---|
+| Tree-sitter code graph (file/symbol/call edges) | Code-aware queries impossible in mem0; their model is conversational |
+| Blast-radius / `get_impact` | Refactor safety mem0 cannot touch |
+| `do_not_revert` decision protection | Active behavior shaping vs. passive retrieval |
+| Hero policies (DecisionLock, ScopeContract, BlastRadius, CrossSession, TokenBudget, LiveStyle, IntentInference) | Completely different category — guardian, not RAG |
+| Lifecycle hooks (PreToolUse, PostToolUse) | mem0 only sees what you `add()`; codevira observes the AI's actual behavior |
+| Phase / roadmap tracking with dependencies | Project-state memory mem0 doesn't model |
+| Confidence via outcome tracking (kept/modified/reverted) | Self-improving memory mem0 has no equivalent of |
+| Fix-history auto-extraction from git | Codebase-grounded memory |
+| Drift detection (commits ≠ phase claim) | Active monitoring, not passive storage |
+| Free forever, no cloud, no caps | mem0 OSS works but graph is paywalled now; codevira's marginal cost per dev is zero |
+
+### mem0 weaknesses we can exploit
+
+1. **Graph dropped from OSS** — opens door for "the open-source memory tool that still has graph"
+2. **Pricing cliff** ($79 → $249 Pro) — cloud-graph is paywalled
+3. **Temporal LongMemEval = 49%** vs Zep 63.8%, Hindsight 91.4%
+4. **No implicit pattern learning** — only explicit facts
+5. **CVSS 8.1 SQL/Cypher injection** (April 2026) on PGVector / Azure MySQL / Neptune backends
+6. **TS SDK trails Python** — only 5 vector stores supported vs 20
+7. **Official MCP repo archived** — community forks fragmenting
+
+---
+
+## Zep (https://getzep.com)
+
+**Positioning:** temporal knowledge graph for AI agents. Strongest at
+"what was true at time T" queries.
+
+**Capability differentiators:** Graphiti (temporal graph),
+LongMemEval 63.8% (vs mem0's 49%), point-in-time queries.
+
+**Weaknesses:** cloud-first (less compelling for solo devs);
+SDK-first (no native MCP); enterprise positioning makes it expensive
+for individuals.
+
+**Threat to codevira:** medium. Different audience (enterprise/teams
+vs solo devs). Watch their pricing if they go down-market.
+
+---
+
+## Letta (formerly MemGPT, https://letta.com)
+
+**Positioning:** "stateful agents" — memory is the agent's persistent
+state across reboots. MemGPT paper authors.
+
+**Capability differentiators:** OS-style memory hierarchy
+(working / archival), self-editing memory, agent-as-process model.
+
+**Weaknesses:** opinionated agent framework lock-in; not just memory.
+Adopting Letta means adopting their agent runtime.
+
+**Threat to codevira:** low. Different category — they're an agent
+framework that includes memory. Codevira is memory that any agent
+framework can use.
+
+---
+
+## Cognee (https://cognee.ai)
+
+**Positioning:** memory + reasoning over enterprise documents.
+
+**Capability differentiators:** ECL (extract-cognify-load) pipeline,
+ontology mapping, knowledge-graph extraction from unstructured docs.
+
+**Weaknesses:** doc-centric, not code-centric; complex setup.
+
+**Threat to codevira:** low. Different audience (enterprise document
+intelligence vs developer code memory).
+
+---
+
+## Claude Projects + auto-memory (Anthropic)
+
+**Positioning:** built-in memory for Claude Code users.
+
+**Capability differentiators:** zero setup (Anthropic ships it),
+deeply integrated into Claude Code UX.
+
+**Weaknesses:** Claude-only (no Cursor/Windsurf reach), cloud-only,
+no decision-shape primitives, no code graph.
+
+**Threat to codevira:** medium-high. Anthropic could add MCP-tool-call
+hooks to Claude Code that capture/replay memory automatically — would
+neutralize codevira's session continuity story for Claude users
+specifically. Mitigation: cross-tool reach + code-aware primitives
+they can't easily replicate.
+
+---
+
+## CLAUDE.md / AGENTS.md / .windsurfrules / etc.
+
+**Positioning:** static markdown files committed to the repo, loaded
+into context on session start.
+
+**Capability differentiators:** zero install, version-controlled,
+team-shareable for free.
+
+**Weaknesses:** static — can't track time-varying state; per-tool
+mirrors duplicate content; ~2,500–3,000 token always-loaded cost;
+human has to maintain.
+
+**Threat to codevira:** low for time-varying memory; high for
+"how to work in this repo" instructions. Codevira should NOT try to
+replace CLAUDE.md — they coexist (CLAUDE.md = static rules,
+codevira = dynamic memory). The benchmark proved this.
+
+---
+
+## Strategic conclusions (drives v2.x prioritization)
+
+**Updated 2026-05-15:** v2.1 renamed to "new-user first contact +
+reliability hardening" after fresh-install testing surfaced 23 silent-
+failure bugs. Public launch (benchmark, demo video, hackathon,
+partnership pitches) moves to v2.2. Hybrid search and the other
+must-close mem0-parity items still ship in v2.1, but framed as
+credibility blockers, not launch-day items.
+
+1. **Hybrid search is still the single highest-leverage capability fix.**
+   Every competitor has it; codevira doesn't; the benchmark publicly
+   fails without it. Ship in v2.1.
+
+2. **Don't try to match mem0 feature-by-feature.** Their wedge is
+   conversational memory at scale. Ours is code-aware behavior shaping.
+   Picking 4 must-close parity items is the right discipline.
+
+3. **mem0 dropping graph from OSS is the opening of the year.**
+   Marketing line for v2.2: "the open-source memory layer that still
+   has the graph." But say it about ourselves; never name them.
+
+4. **The benchmark is the moat.** Publishing a neutral, runnable
+   benchmark that includes mem0/Zep/Letta means we set the conversation.
+   Even when we lose on a dimension, we're the steward of the category.
+
+5. **Cross-tool is uncopiable.** mem0/Zep/Letta will not become
+   cross-tool because their business model assumes lock-in. Codevira's
+   MCP-only architecture makes this structural, not just a feature.
+
+---
+
+## Tracking template (when adding a new competitor)
+
+```
+## <name> (<url>)
+
+**Positioning:** <one sentence>
+
+**Capability differentiators:** <bullets>
+
+**Weaknesses:** <bullets>
+
+**Threat to codevira:** <low/medium/high>. <why>
+```
+
+---
+
+## Refresh log
+
+- 2026-05-15 — initial creation. mem0 deep dive (Sachin + Claude
+  research agent, 19 tool calls, ~158k ms). Zep/Letta/Cognee/Claude
+  Projects/CLAUDE.md profiled from prior knowledge — refresh by
+  research agent next quarter.