Zero token cost · Persists across sessions · Agent-agnostic
It's 4am. The token counter is spinning like a slot machine and Claude is failing on a problem you've solved a hundred times across a hundred projects. OWE is the fix: a local database that grows with every session, every repo, every agent — turning a perpetual junior into something that actually remembers.
English | Italiano
Task → OWE search (zero tokens) → GitPilfer → Write from scratch
Before touching a single file, the agent queries a local SQLite index. If a tested solution exists, it reuses it. If not, it falls through to GitHub search, then writes from scratch. The database grows silently in the background. The more sessions it accumulates, the less the agent has to reinvent.
| Layer | Contents |
|---|---|
| Code | Functions indexed by name, docstring, parameters, call graph, and exact line coordinates |
| Knowledge | API quirks, dead ends, unexpected behaviors — organized by domain |
| Preferences | How you want the agent to behave — loaded into context every session, automatically |
- Storage — SQLite + FTS5 (
~/.owe/owe.db) — BM25 full-text ranking, zero latency - Parsing — tree-sitter (Python, JS, TS) — exact AST coordinates, not regex guesses
- Sync — watchdog file watcher — incremental SQLite updates on every file change
- Dependencies — tree-sitter and watchdog auto-install via pip on first run
- Portability — Unix and Windows (Git Bash / WSL) — one database, any machine
git clone https://github.com/pilgrimdelamare/owe-skill.git
cd owe-skill
bash install.shinstall.sh copies the skill, patches ~/.claude/CLAUDE.md, and launches the initial census — all in one shot. The only thing it asks is which folders to scan. After that: you never touch it again. The file watcher keeps the index current on every save, and the agent queries it automatically at the start of every session.
Open Settings → Cascade → Global Rules and paste the contents of owe-skill/SKILL.md.
cat owe-skill/SKILL.md > /path/to/your-project/.windsurfrulesOWE indexes code in three passes. Each pass is additive — run them once after the initial setup.
| Level | Command | What it adds |
|---|---|---|
| Light (0) | census.py |
Function names, docstrings, auto-tags, exact line range |
| Medium (1) | census.py --medium |
Parameters, call graph — what calls what |
| Heavy (2) | census.py --heavy |
File mtime snapshot for coordinate staleness detection |
python ~/.claude/skills/owe-skill/scripts/census.py
python ~/.claude/skills/owe-skill/scripts/census.py --medium
python ~/.claude/skills/owe-skill/scripts/census.py --heavyNo file copying. Heavy census stores only a mtime timestamp in SQLite. Function bodies are read on demand via exact line coordinates (
path:start-end). Zero disk overhead.
verify.py --status shows the breakdown per level at any time.
At startup — automatically:
- Checks
~/.owe/owe.dbexists - Runs
verify.py --statusand reports the dashboard - Runs
prefs.py --loadand injects preferences into context
Before every task — automatically:
- Searches the local index:
search.py keyword1 keyword2 - Reuses what it finds — or falls through to GitPilfer, then scratch
You never run these commands manually.
| Script | Purpose |
|---|---|
_db.py |
Shared SQLite module — schema, FTS5 triggers, migration |
census.py |
Scan and manage components (--medium, --heavy, --add, --remove) |
search.py |
FTS5 BM25 search — returns FOUND:N + ranked results |
verify.py |
Check stale paths, stale knowledge, census level breakdown |
prefs.py |
User preference CRUD (--add, --list, --remove, --load) |
export_import.py |
Vault backup and restore via zip |
watcher.py |
File watcher — incremental sync on every save |
| Command | Action |
|---|---|
/owe-sync |
Re-scan configured folders |
/owe-setup |
Reconfigure folders and extensions |
/owe-status |
Dashboard: components, knowledge, preferences, census levels, stale entries |
/owe-pref |
Add a user preference |
/owe-autosync-on |
Add new components without confirmation |
/owe-autosync-off |
Revert to asking before adding |
/owe-export |
Zip ~/.owe/ to Desktop |
/owe-import |
Restore from Desktop zip |
~/.owe/
├── owe.db # Everything — components, knowledge, preferences, config
└── knowledge/
└── <domain>/
└── notes.json
| Column | Description |
|---|---|
path |
Absolute path to the source file |
name |
Function or method name |
line / end_line |
Exact line range — body readable on demand without loading the full file |
file_mtime |
Mtime at last heavy census — used to detect stale coordinates |
docstring |
First docstring line, truncated to 120 chars |
tags |
Auto-generated from name, filename, and parent folder |
params / calls |
Parameters string and call graph (medium census) |
census_level |
0 = light · 1 = medium · 2 = heavy |
- Components — added with confirmation (silent if
autosync: true) - Knowledge notes — never added without confirmation
- Preferences — never added without confirmation
- Stale entries — flagged by
verify.py, never silently ignored (default threshold: 30 days)
python export_import.py --export # zips ~/.owe/ to Desktop
python export_import.py --import # restores from Desktop zip (backs up current to ~/.owe.bak/)Transfer via USB or any manual method. No cloud, no sync, no account.
OWE is agent-agnostic. The same database works on Claude Code, Windsurf, or any agent running on the same machine. The watcher picks up changes from any of them. With autosync: off (default), new components are proposed, not silently added.
Zero token · Persiste tra sessioni · Funziona su qualsiasi agente
Sono le 4 del mattino. Il contatore dei token gira come una slot machine e Claude sta fallendo su un problema che hai risolto cento volte in cento progetti diversi. OWE è la soluzione: un database locale che cresce a ogni sessione, ogni repo, ogni agente — trasformando un eterno junior in qualcosa che finalmente si ricorda.
English | Italiano
Task → Ricerca OWE (zero token) → GitPilfer → Scrivi da zero
Prima di toccare un singolo file, l'agente interroga un indice SQLite locale. Se esiste una soluzione già testata, la riusa. Se no, passa alla ricerca su GitHub, poi scrive da zero. Il database cresce silenziosamente in background. Più sessioni accumula, meno l'agente deve reinventare.
| Layer | Contenuto |
|---|---|
| Codice | Funzioni indicizzate per nome, docstring, parametri, call graph e coordinate di riga esatte |
| Conoscenza | Quirk di API, vicoli ciechi, comportamenti inattesi — organizzati per dominio |
| Preferenze | Come vuoi che l'agente si comporti — caricate in context a ogni sessione, in automatico |
- Storage — SQLite + FTS5 (
~/.owe/owe.db) — ranking BM25, zero latenza - Parsing — tree-sitter (Python, JS, TS) — coordinate AST esatte, non regex
- Sync — file watcher watchdog — aggiornamento incrementale SQLite a ogni salvataggio
- Dipendenze — tree-sitter e watchdog si auto-installano via pip al primo avvio
- Portabilita' — Unix e Windows (Git Bash / WSL) — un database, qualsiasi macchina
git clone https://github.com/pilgrimdelamare/owe-skill.git
cd owe-skill
bash install.shinstall.sh copia la skill, aggiorna ~/.claude/CLAUDE.md e avvia il censimento iniziale — tutto in un colpo solo. L'unica cosa che chiede e' quali cartelle scansionare. Dopo: non lo tocchi piu'. Il file watcher aggiorna l'indice a ogni salvataggio, e l'agente lo interroga in automatico all'avvio di ogni sessione.
Apri Settings → Cascade → Global Rules e incolla il contenuto di owe-skill/SKILL.md.
cat owe-skill/SKILL.md > /percorso/tuo-progetto/.windsurfrulesOWE indicizza il codice in tre passaggi. Ogni passaggio e' additivo — eseguili una volta dopo il setup iniziale.
| Livello | Comando | Cosa aggiunge |
|---|---|---|
| Light (0) | census.py |
Nomi funzione, docstring, tag automatici, range di riga esatto |
| Medio (1) | census.py --medium |
Parametri, call graph — cosa chiama cosa |
| Pesante (2) | census.py --heavy |
Snapshot mtime per rilevamento staleness delle coordinate |
python ~/.claude/skills/owe-skill/scripts/census.py
python ~/.claude/skills/owe-skill/scripts/census.py --medium
python ~/.claude/skills/owe-skill/scripts/census.py --heavyNessuna copia di file. Il censimento pesante salva solo un timestamp mtime in SQLite. I corpi delle funzioni vengono letti su richiesta tramite coordinate di riga esatte (
path:start-end). Zero overhead su disco.
verify.py --status mostra la suddivisione per livello in qualsiasi momento.
All'avvio — in automatico:
- Controlla che
~/.owe/owe.dbesista - Esegue
verify.py --statuse riporta il dashboard - Esegue
prefs.py --loade inietta le preferenze in context
Prima di ogni task — in automatico:
- Cerca nell'indice locale:
search.py keyword1 keyword2 - Riusa quello che trova — o passa a GitPilfer, poi scrive da zero
Non lanci mai questi comandi manualmente.
| Script | Funzione |
|---|---|
_db.py |
Modulo SQLite condiviso — schema, trigger FTS5, migrazione |
census.py |
Scansione e gestione componenti (--medium, --heavy, --add, --remove) |
search.py |
Ricerca FTS5 BM25 — restituisce FOUND:N + risultati ordinati |
verify.py |
Controlla path stale, conoscenza stale, breakdown livelli censimento |
prefs.py |
CRUD preferenze utente (--add, --list, --remove, --load) |
export_import.py |
Backup e ripristino vault via zip |
watcher.py |
File watcher — sync incrementale a ogni salvataggio |
| Comando | Azione |
|---|---|
/owe-sync |
Riscansiona le cartelle configurate |
/owe-setup |
Riconfigura cartelle ed estensioni |
/owe-status |
Dashboard: componenti, conoscenza, preferenze, livelli censimento, entry stale |
/owe-pref |
Aggiunge una preferenza utente |
/owe-autosync-on |
Aggiunge nuovi componenti senza chiedere conferma |
/owe-autosync-off |
Torna a chiedere conferma prima di aggiungere |
/owe-export |
Comprime ~/.owe/ sul Desktop |
/owe-import |
Ripristina dal zip sul Desktop |
~/.owe/
├── owe.db # Tutto — componenti, conoscenza, preferenze, config
└── knowledge/
└── <dominio>/
└── notes.json
| Colonna | Descrizione |
|---|---|
path |
Path assoluto al file sorgente |
name |
Nome della funzione o metodo |
line / end_line |
Range di riga esatto — corpo leggibile su richiesta senza caricare il file intero |
file_mtime |
Mtime all'ultimo censimento pesante — usato per rilevare coordinate stale |
docstring |
Prima riga di docstring, troncata a 120 char |
tags |
Generati automaticamente da nome, filename e cartella padre |
params / calls |
Stringa parametri e call graph (censimento medio) |
census_level |
0 = light · 1 = medio · 2 = pesante |
- Componenti — aggiunti con conferma (silenzioso se
autosync: true) - Note di conoscenza — mai aggiunte senza conferma
- Preferenze — mai aggiunte senza conferma
- Entry stale — segnalate da
verify.py, mai ignorate silenziosamente (soglia default: 30 giorni)
python export_import.py --export # comprime ~/.owe/ sul Desktop
python export_import.py --import # ripristina dal zip (backup corrente in ~/.owe.bak/)Trasferimento via USB o metodo manuale a scelta. Niente cloud, niente sync, niente account.
OWE e' agnostico rispetto all'agente. Lo stesso database funziona su Claude Code, Windsurf o qualsiasi altro agente sulla stessa macchina. Il watcher rileva le modifiche da chiunque. Con autosync: off (default), i nuovi componenti vengono proposti, non aggiunti silenziosamente.