# Product Definition

## Working Name

`spool` is evolving from a context extractor into a local-first developer memory operating system.

## Product Vision

Give developers a private, durable, structured memory layer that makes different AI tools progressively better aligned with:

- the developer
- the project
- the team's decisions
- the developer's long-term working patterns

## Core Product Statement

`spool` should let Claude, Codex, ChatGPT, Cursor, local models, and future AI clients connect to the same trusted local knowledge base without requiring the developer to re-teach each tool from scratch.

## Problem

Today, useful developer memory is fragmented across:

- code repositories
- Obsidian notes
- chat transcripts
- terminal sessions
- commits and pull requests
- postmortems and ad hoc docs

AI tools usually see only the current prompt plus a narrow code window. That causes repeated context loss, inconsistent advice, and poor long-term adaptation to the developer.

## Primary Users

1. solo developers with heavy Obsidian usage
2. power users working across multiple AI clients
3. security-conscious developers who do not want cloud memory systems
4. small teams who want shared patterns without surrendering raw internal context

## Product Principles

### 1. Local First

Raw memory, indexes, and retrieval should default to local storage and local execution.

### 2. Security First

Sensitive developer knowledge must not be exposed to an AI client unless policy explicitly permits it.

### 3. Obsidian as Knowledge of Record

Obsidian remains the trusted, human-readable, inspectable long-term knowledge layer.

### 4. Model-Agnostic Gateway

No hard dependency on one AI vendor or one client.

### 5. Structured Memory Over Chat Logs

The goal is not to archive raw prompts blindly. The goal is to build reliable memory objects such as decisions, preferences, incidents, patterns, and constraints.

### 6. Provenance Matters

Every memory item should have traceable origin and confidence.

## What `spool` Must Eventually Do

### Current Capability

- route from `cwd` to a project
- scan selected Obsidian roots
- rank notes by heuristic relevance
- render compact context for different AI tools
- generate wake-up packets with policy-aware suppression/redaction reporting
- capture memory records in a local append-only ledger
- manage lifecycle state for manual/proposed memory
- expose read/write memory flows through CLI and MCP
- provide an experimental GUI workbench for lifecycle review
- support an optional read-only daemon boundary for repeated lifecycle reads

### Target Capability

- capture raw memory events from developer workflows
- distill events into durable memory objects
- maintain a wake-up packet for each AI session
- enforce policy-aware retrieval
- expose the same memory substrate to multiple AI clients

## Memory Classes

`spool` should support at least these memory classes:

- `project`
- `decision`
- `preference`
- `constraint`
- `pattern`
- `incident`
- `person`
- `workflow`
- `session`

## Non-Goals

- replacing Obsidian as a note-taking app
- becoming a generic cloud note platform
- inventing a compression dialect as the primary value proposition
- acting like a black-box memory agent that decides everything automatically

## Position on AAAK-like Compression

Dense memory compression is useful, but it is not the core of the system.

Priority order:

1. structured memory model
2. trustworthy retrieval
3. security and provenance
4. wake-up packets and summaries
5. optional compact memory formats

## Product Success Criteria

### Developer Experience

- less repeated explanation across AI tools
- fewer missing-project-context failures
- faster ramp-up for returning to inactive projects

### Retrieval Quality

- relevant context appears in top results consistently
- irrelevant vault noise stays out
- decisions and constraints are surfaced before generic notes

### Security

- sensitive content is classifiable and enforceable
- local-only mode remains fully usable
- memory retrieval is auditable

### Ecosystem Reach

- one local memory substrate can serve multiple AI clients

## Current Product Gap

The current repository is beyond a routing prototype, but it is still missing major product slices:

- workflow importers for transcript, git, and terminal signals
- durable extraction/distillation pipeline for decisions, incidents, and patterns
- promotion flow from ledger records into curated Obsidian knowledge
- richer retrieval intelligence such as contradiction detection, confidence scoring, stale-memory detection, and semantic retrieval
- a finished desktop product surface on top of the existing Rust desktop facade
- long-term distillation workflows
