learning-agent 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Storage Enhancements**
+  - Compaction system for archiving old lessons and removing tombstones
+  - Smart sync: rebuild index only when JSONL changes
+  - Retrieval count tracking for lesson usage statistics
+
+- **CLI Commands**
+  - `learning-agent import <file>` - Import lessons from JSONL file
+  - `learning-agent stats` - Show database health statistics
+  - `learning-agent compact` - Archive old lessons
+  - `learning-agent export` - Export lessons as JSON
+  - Global flags: `--verbose`, `--quiet`
+  - Colored output with chalk
+
+- **Embeddings**
+  - Switched to EmbeddingGemma-300M (~278MB, down from ~500MB)
+  - Simplified model download using node-llama-cpp resolveModelFile
+
+- **Testing**
+  - 100% statement/function/line coverage (435 tests)
+  - Property-based tests with fast-check
+  - Integration tests for capture workflows
+
+### Changed
+
+- Unified QuickLesson and FullLesson into single Lesson type
+- Removed deprecated type exports
+
+## [0.1.0] - 2025-01-30
+
+### Added
+
+- **Core Storage**
+  - JSONL storage for lessons with atomic append operations
+  - SQLite index with FTS5 full-text search support
+  - Automatic index rebuild from JSONL source of truth
+  - Hybrid storage model: git-tracked JSONL + rebuildable SQLite cache
+
+- **Embeddings**
+  - Local semantic embeddings via node-llama-cpp
+  - EmbeddingGemma-300M model (768 dimensions)
+  - Manual model download via CLI (~278MB)
+  - Model stored in `~/.node-llama-cpp/models/`
+
+- **Search & Retrieval**
+  - Vector similarity search using cosine distance
+  - Ranking with configurable boosts (severity, recency, confirmation)
+  - Session-start retrieval for high-severity lessons
+  - Plan-time retrieval with semantic relevance
+
+- **Capture System**
+  - User correction detection patterns
+  - Self-correction detection (edit-fail-re-edit cycles)
+  - Test failure detection and fix tracking
+  - Quality filter: novel, specific, and actionable checks
+
+- **Lesson Types**
+  - Quick lessons for fast capture
+  - Full lessons with evidence and severity levels
+  - Tombstone records for deletions/edits
+  - Metadata: source, context, supersedes, related
+
+- **Public API**
+  - `appendLesson()` - Store new lessons
+  - `readLessons()` - Read lessons with pagination
+  - `searchKeyword()` - FTS5 keyword search
+  - `searchVector()` - Semantic vector search
+  - `loadSessionLessons()` - Session-start high-severity lessons
+  - `retrieveForPlan()` - Plan-time relevant lesson retrieval
+  - Detection triggers: `detectUserCorrection()`, `detectSelfCorrection()`, `detectTestFailure()`
+  - Quality filters: `shouldPropose()`, `isNovel()`, `isSpecific()`, `isActionable()`
+
+- **CLI**
+  - `pnpm learn` - Capture a lesson manually
+  - `learning-agent search` - Search lessons
+  - `learning-agent rebuild` - Rebuild SQLite index
+
+- **Developer Experience**
+  - TypeScript with ESM modules
+  - Zod schemas for runtime validation
+  - Vitest test suite
+  - tsup build configuration
+
+[Unreleased]: https://github.com/nathanbraun/learning_agent/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nathanbraun/learning_agent/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nathan Delacrétaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# Learning Agent
+
+A repository-scoped learning system that helps Claude Code avoid repeating mistakes across sessions. Captures lessons from corrections and retrieves them when relevant.
+
+## Overview
+
+Claude Code forgets lessons between sessions. This leads to:
+- Repeated mistakes across sessions
+- Users re-explaining preferences
+- No memory of what worked or failed
+
+Learning Agent solves this by capturing lessons when corrections happen and retrieving relevant ones at session start and plan time.
+
+## Installation
+
+```bash
+# Using pnpm (recommended)
+pnpm add -D learning-agent
+
+# Using npm
+npm install --save-dev learning-agent
+```
+
+After installation, download the embedding model (~278MB, one-time):
+
+```bash
+npx learning-agent download-model
+```
+
+### Requirements
+
+- Node.js >= 20
+- ~278MB disk space for embedding model
+- ~150MB RAM for embedding operations
+
+## Quick Start
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm build
+
+# Run tests
+pnpm test
+
+# Download embedding model (first use)
+pnpm download-model
+```
+
+## Architecture
+
+```
+.claude/                        (repository scope)
+|-- CLAUDE.md                   <- Always loaded (permanent rules)
+|-- lessons/
+|   |-- index.jsonl             <- Source of truth (git-tracked)
+|   +-- archive/                <- Old lessons (compacted)
++-- .cache/
+    +-- lessons.sqlite          <- Rebuildable index (.gitignore)
+```
+
+### Data Flow
+
+```
++----------+    +----------+    +----------+    +----------+
+| Mistake  |--->| Claude   |--->| Quick    |--->| Stored   |
+| happens  |    | notices  |    | confirm  |    | lesson   |
++----------+    +----------+    +----------+    +----------+
+                     |              |
+                (or user          [y/n]
+                 corrects)
+
++----------+    +----------+    +----------+
+|  Next    |<---| Retrieve |<---| Session  |
+|  task    |    | relevant |    |  start   |
++----------+    +----------+    +----------+
+```
+
+## Features
+
+- **Lesson Capture**: Detects user corrections, self-corrections, and test failure fixes
+- **Quality Filter**: Prevents vague or obvious lessons (must be novel, specific, actionable)
+- **Vector Search**: Local semantic search using nomic-embed-text-v1.5 via node-llama-cpp
+- **Hybrid Storage**: JSONL source of truth (git-tracked) with SQLite FTS5 index (rebuildable)
+- **Offline First**: No external API dependencies; works completely offline
+- **Retrieval Timing**: High-severity lessons at session start; relevant lessons at plan time
+
+## CLI Usage
+
+```bash
+# Capture a lesson manually
+pnpm learn "Use Polars for large files, not pandas"
+
+# Search lessons
+learning-agent search "data processing"
+
+# Rebuild index from JSONL
+learning-agent rebuild
+
+# List all lessons
+learning-agent list
+
+# Show database stats
+learning-agent stats
+
+# Compact and archive old lessons
+learning-agent compact
+```
+
+## Claude Code Integration
+
+Add to your `.claude/settings.json` to automatically load lessons:
+
+```json
+{
+  "hooks": {
+    "session_start": "npx learning-agent load-session",
+    "pre_plan": "npx learning-agent check-plan"
+  }
+}
+```
+
+### Hook Commands
+
+| Command | Purpose |
+|---------|---------|
+| `load-session` | Load high-severity lessons at session start |
+| `check-plan` | Retrieve relevant lessons when planning |
+
+## API Reference
+
+```typescript
+import {
+  // Storage
+  appendLesson, readLessons, searchKeyword, rebuildIndex, closeDb,
+
+  // Search
+  searchVector, cosineSimilarity, rankLessons,
+
+  // Capture
+  shouldPropose, isNovel, isSpecific, isActionable,
+  detectUserCorrection, detectSelfCorrection, detectTestFailure,
+
+  // Retrieval
+  loadSessionLessons, retrieveForPlan, formatLessonsCheck,
+
+  // Types
+  type Lesson, LessonSchema, generateId,
+} from 'learning-agent';
+```
+
+See [examples/](examples/) for usage examples.
+
+## Lesson Types
+
+### Quick Lesson (fast capture)
+```json
+{
+  "id": "L001",
+  "type": "quick",
+  "trigger": "Used pandas for 500MB file",
+  "insight": "Polars 10x faster",
+  "tags": ["performance", "polars"],
+  "source": "user_correction"
+}
+```
+
+### Full Lesson (detailed, high-severity)
+```json
+{
+  "id": "L002",
+  "type": "full",
+  "trigger": "Auth API returned 401 despite valid token",
+  "insight": "API requires X-Request-ID header",
+  "evidence": "Traced in network tab, header missing",
+  "severity": "high",
+  "source": "test_failure"
+}
+```
+
+## Technology Stack
+
+| Component | Technology |
+|-----------|------------|
+| Language | TypeScript (ESM) |
+| Package Manager | pnpm |
+| Build | tsup |
+| Testing | Vitest |
+| Storage | better-sqlite3 + FTS5 |
+| Embeddings | node-llama-cpp + nomic-embed-text-v1.5 |
+| CLI | Commander.js |
+| Schema | Zod |
+
+## Development
+
+```bash
+# Watch mode (rebuild on changes)
+pnpm dev
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Type checking
+pnpm lint
+```
+
+## Project Status
+
+Version 0.1.0 - Core infrastructure implemented. See [doc/SPEC.md](doc/SPEC.md) for the full specification and [doc/PLAN.md](doc/PLAN.md) for the implementation roadmap.
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [doc/SPEC.md](doc/SPEC.md) | Complete specification |
+| [doc/CONTEXT.md](doc/CONTEXT.md) | Research and design decisions |
+| [doc/PLAN.md](doc/PLAN.md) | Implementation plan |
+| [AGENTS.md](AGENTS.md) | Agent instructions overview |
+| [.claude/CLAUDE.md](.claude/CLAUDE.md) | Claude Code project instructions |
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node