# 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