Metadata-Version: 2.4
Name: corvid-remember
Version: 0.3.0
Summary: Permanent memory layer for AI coding agents
Author: juraxis
License-Expression: MIT
Project-URL: Homepage, https://github.com/juraxis/corvid
Project-URL: Repository, https://github.com/juraxis/corvid
Keywords: ai,memory,coding-agent,claude,codex,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastembed>=0.4.0
Requires-Dist: sqlite-vec>=0.1.0
Provides-Extra: lite

# corvid

A permanent memory layer for AI coding agents. Installs as a native skill. One command: `/remember`.

Inspired by Karpathy's [llm-wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) for building knowledge bases with LLMs, but instead of ingesting external docs, corvid captures what you learn during the conversation itself.

### What's new in 0.3.0

The retrieval engine learns from usage and enforces itself.

- **Memory feedback loop** — articles that appear in search results get a ranking boost on future searches. The system learns what matters.
- **PreToolUse hook** — `corvid install` injects a Claude Code hook that reminds the agent to check the wiki before grepping files. Enforced, not hoped for.
- **Article relations** — markdown links between articles create navigable edges. JSON search results include `"related"` articles so the agent discovers connected knowledge without extra searches.
- **Confidence scoring** — facts carry confidence levels (low/med/high). Regex-extracted = low, letting agents know what to trust vs verify.

### 0.2.0

- **Reciprocal Rank Fusion** — keyword and semantic results merged by agreement, not appended.
- **Tag pre-filtering** — `--tags deploy,auth` narrows search space before computing similarity.
- **Temporal facts** — structured facts with contradiction detection. `corvid facts` shows current vs superseded.
- **Smart snippets** — best paragraph by query relevance, not first 200 characters.

## Why

Every AI session starts from zero. You figure something out, close the terminal, and next month your agent has no memory of it.

Built-in memory is per-project, 200 lines, no search. corvid gives you cross-project memory with semantic search. What you figure out once stays figured out.

## Install

```bash
pip install corvid-remember
corvid install
```

`corvid install` detects your agents (Claude Code, Codex, Gemini CLI) and adds `/remember` as a native skill in each one.

```
$ corvid install

  ✓ Claude Code      → ~/.claude/skills/remember/SKILL.md
  ✓ Codex CLI        → ~/.codex/skills/remember/SKILL.md

  Wiki: ~/corvid
  Semantic search: enabled (BAAI/bge-small-en-v1.5)
```

Lightweight mode (keyword search only, no embedding model):

```bash
pip install corvid-remember[lite]
corvid install
```

## How it works

Say `/remember` and your agent distills the current insight into a searchable article:

```
You: /remember the Google OAuth deploy gotchas

corvid writes → ~/corvid/wiki/auth/google-oauth-deploy-gotchas.md

  # Google OAuth Deploy Issues
  Three things break after deploy that work locally:
  1. Callback URL must match EXACT casing in Google Console
  2. Consent screen redirect URI needs the production domain with https
  3. Cookie SameSite=None + Secure required behind reverse proxy
  Symptoms: silent 400 on redirect, no error in server logs.
```

Next session, any project, your agent pulls up what you already solved.

## Search

Two search modes, both local, both fast. Results merged via [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf) — when both methods agree on a result, it ranks highest.

**Keyword** (always on): [SQLite FTS5](https://www.sqlite.org/fts5.html) with Porter stemming and BM25 ranking. "Finetuning" matches "fine-tuned." Zero dependencies.

**Semantic** (full install): [fastembed](https://github.com/qdrant/fastembed) generates embeddings with a 33MB model ([bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5)), [sqlite-vec](https://github.com/asg017/sqlite-vec) stores and searches them inside the same SQLite database. "Login callback issue" finds your article about "OAuth redirect" even though it never uses those words. Runs on CPU in ~50ms. No GPU. No server. No API calls.

**Tag filtering**: Articles can include a `tags:` line. Search with `--tags` to narrow results before computing similarity — fewer results, higher precision.

```bash
corvid search "oauth redirect"
corvid search "deploy config" --tags gcp,docker
corvid search "liability caps" --json
```

## Built-in memory vs corvid

No clash — they complement. Built-in memory loads everything every turn for project prefs; corvid uses embeddings to retrieve only what's relevant, so you store more knowledge while consuming fewer tokens per conversation.

| | Built-in | corvid |
|---|---|---|
| Scope | Per-project | Cross-project |
| Limit | ~200 lines | Unlimited |
| Retrieval | Entire file loaded into context | Search by keyword + semantic similarity |
| Token cost | Grows with memory size | Only relevant results enter context |
| Control | You or agent decides | You decide with `/remember` |

## What people save

- The auth fix that works locally but breaks after deploy
- The contract clause taxonomy the parser needs to handle
- The database index that stopped the timeout
- The API behavior that is not in the docs
- The architecture decision and why you made it
- The deploy config that makes CI pass after it randomly started failing

## What gets saved

Your agent writes markdown articles by category with tags for search filtering. You never touch the structure.

```
~/corvid/
  corvid.db          # search index (disposable, rebuildable)
  INDEX.md           # table of contents your agent maintains
  wiki/
    auth/
      google-oauth-deploy-gotchas.md    # tags: auth, deploy, oauth
    contracts/
      liability-cap-types.md            # tags: contracts, liability
    backend/
      supabase-rls-service-role.md      # tags: supabase, rls, auth
```

Real articles with tables, exact values, commands, reasoning. Not chat logs.

## Temporal facts

corvid extracts structured facts from articles during indexing. When a fact changes, the old one gets marked as superseded — not deleted.

```
$ corvid facts Backend
  Backend → uses → Postgres 16
  Backend → uses → Postgres 15 [superseded 2025-11-03]
```

No more contradicting articles sitting side by side. You know what's current and what's history.

## Under the hood

One Python file. [SQLite FTS5](https://www.sqlite.org/fts5.html) for keyword search. [sqlite-vec](https://github.com/asg017/sqlite-vec) for vector search. [fastembed](https://github.com/qdrant/fastembed) for embeddings (ONNX, CPU-only, 33MB). Results ranked by [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf). Tag-based pre-filtering narrows the search space before computing similarity. Temporal facts table tracks when knowledge gets superseded. Everything local. Database is disposable, rebuild anytime with `corvid index-all`.

## Commands

| Command | What it does |
|---|---|
| `corvid install` | Detect agents, install `/remember` skill, init database |
| `corvid search <query>` | Search (human-readable) |
| `corvid search <query> --json` | Search (JSON for agents) |
| `corvid search <q> --tags x,y` | Filter by tags before searching |
| `corvid facts [subject]` | Show extracted facts (current + superseded) |
| `corvid index <file>` | Index one markdown file |
| `corvid index-all` | Re-index everything |
| `corvid stats` | Show article counts |

## License

MIT
