pi-recollect 0.3.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.4.1 (2026-05-13)
+
+### Added
+- Comprehensive documentation
+
+## 0.4.0 (2026-05-12)
+
+### Added
+- Memory Store (SQLite)
+- Semantic Search (FTS5/BM25)
+- Graph Memory
+- Memory Decay
+- Session Continuity
+
+## 0.3.0 (Earlier)
+- Initial release

package/README.md

@@ -1,72 +1,60 @@
 # pi-recollect
 
-Memory and context management extension for coding agents.
+Persistent memory extension for Pi coding agents.
 
 ## Features
 
-- **Graph Memory** - Hash-based ID memory with dependencies
-- **Context Compaction** - Session compaction for long conversations
-- **Memory Decay** - Semantic summarization of old content
-- **Progressive Disclosure** - Layered context presentation
-- **Session Continuity** - Seamless session recovery
+- **Memory Store** - SQLite-backed persistent memory
+- **Semantic Search** - FTS5/BM25 search across memories
+- **Session Continuity** - Continue from where you left off
+- **Knowledge Compounding** - Store lessons learned
+- **Graph Memory** - Hash-based graph relationships
+- **Memory Decay** - Age out old memories
+- **Context Saving** - Save context between sessions
+- **Session Isolation** - Separate memories per session
 
-## Installation
+## Install
 
 ```bash
-npm install pi-recollect
+pi install npm:pi-recollect
 ```
 
-## Usage
+## Quick Start
 
-### Commands
-
-- `/remember [insight]` - Store insight in graph memory
-- `/recall [topic]` - Recall related memories
-- `/compact` - Compact session context
-- `/forget [id]` - Remove from memory
-
-### Graph Store
-
-```typescript
-import { createGraphStore, generateHashId } from 'pi-recollect';
+### Store Memory
+```bash
+/memory store "Important: Use auth middleware for /api routes"
+```
 
-const store = createGraphStore();
+### Search Memory
+```bash
+/memory search authentication
+```
 
-// Add memory node
-const node = store.addNode({
-  type: 'insight',
-  title: 'Important finding',
-  content: '...',
-  relations: [{ type: 'relates_to', targetId: otherNode.id }],
-});
+### Recall Context
+```bash
+/memory recall
+```
 
-// Query memories
-const insights = store.query({ type: 'insight', closed: false });
+### List Memories
+```bash
+/memory list
 ```
 
-## Architecture
+## Commands
 
-```
-src/
-├── graph/
-│   ├── graph-store.ts     # Graph memory
-│   ├── hash-id.ts         # Hash-based IDs
-│   ├── memory-store.ts    # Memory persistence
-│   └── decay.ts           # Memory decay
-├── context/
-│   └── context-saver.ts   # Context management
-├── session/
-│   └── session-continuity.ts
-└── index.ts
-```
+| Command | Description |
+|---------|-------------|
+| `/memory` | Memory main command |
+| `/memory store` | Store new memory |
+| `/memory search` | Search memories |
+| `/memory recall` | Recall context |
 
-## Patterns Applied
+## Verify
 
-- Hash-based IDs from beads
-- Graph memory from beads
-- Memory categories from pi-hermes-memory
-- Context compaction from oh-my-pi
-- Memory decay from beads
+```bash
+pi list
+```
 
 ## License
 

package/docs/API.md

@@ -0,0 +1,62 @@
+# pi-recollect API Reference
+
+## Graph Store
+
+```typescript
+import { createGraphStore, generateHashId } from 'pi-recollect';
+
+const store = createGraphStore();
+
+// Add nodes
+const issue = store.addNode({
+  type: 'issue',
+  title: 'Bug in auth',
+  content: 'Token expiry check wrong',
+  relations: [],
+});
+
+const task = store.addNode({
+  type: 'task',
+  title: 'Fix auth',
+  relations: [{ type: 'blocks', targetId: issue.id }],
+});
+
+// Query
+const insights = store.query({ type: 'insight' });
+const tasks = store.query({ type: 'task', closed: false });
+
+// Get related
+const related = store.getRelatedNodes(issue.id);
+const relations = store.getRelations(issue.id);
+
+// Close and compact
+store.closeNode(issue.id);
+store.compact(new Date('2024-01-01'));
+```
+
+## Hash IDs
+
+```typescript
+import { generateHashId } from 'pi-recollect';
+
+const id = generateHashId('issue');
+// "issue-a1b2c3d4"
+
+const id2 = generateHashId();
+// "node-e5f6g7h8"
+```
+
+## Memory Decay
+
+```typescript
+import { createMemoryDecay } from 'pi-recollect';
+
+const decay = createMemoryDecay({
+  decayThreshold: 30 * 24 * 60 * 60 * 1000, // 30 days
+  minImportance: 0.5,
+});
+
+decay.record(node);
+const shouldDecay = decay.shouldDecay(node);
+const summary = decay.summarize(node);
+```

package/docs/COMMANDS.md

@@ -0,0 +1,177 @@
+# Command Reference - pi-recollect
+
+## Slash Commands
+
+### /memory
+Main memory command.
+
+```bash
+/memory <subcommand> [options]
+```
+
+### /memory store
+Store new memory.
+
+```bash
+/memory store <content> [options]
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--tags` | Comma-separated tags |
+| `--priority` | high/normal/low |
+| `--expires` | Auto-delete duration |
+
+### /memory search
+Search memories.
+
+```bash
+/memory search <query> [options]
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--tags` | Filter by tags |
+| `--priority` | Filter by priority |
+| `--limit` | Max results |
+| `--fuzzy` | Enable fuzzy matching |
+
+### /memory recall
+Recall session context.
+
+```bash
+/memory recall [options]
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--session` | Specific session ID |
+| `--recent` | Recent sessions only |
+
+### /memory list
+List memories.
+
+```bash
+/memory list [options]
+```
+
+#### Options
+
+| Option | Description |
+|--------|-------------|
+| `--tags` | Filter by tags |
+| `--status` | active/archived |
+| `--limit` | Max results |
+
+### /memory get
+Get specific memory.
+
+```bash
+/memory get <id>
+```
+
+### /memory update
+Update memory.
+
+```bash
+/memory update <id> <content>
+```
+
+### /memory delete
+Delete memory.
+
+```bash
+/memory delete <id>
+```
+
+### /memory link
+Link memories.
+
+```bash
+/memory link <id> --to <id> --type=<type>
+```
+
+### /memory graph
+Show memory graph.
+
+```bash
+/memory graph [id]
+```
+
+### /memory archive
+Archive old memories.
+
+```bash
+/memory archive [options]
+```
+
+### /memory save-session
+Save current session.
+
+```bash
+/memory save-session
+```
+
+### /memory resume
+Resume last session.
+
+```bash
+/memory resume
+```
+
+## Tools
+
+### memory_store
+
+```javascript
+memory_store({
+  content: "Memory text",
+  tags: ["tag1", "tag2"],
+  priority: "normal",
+  expires: "7d"
+})
+```
+
+### memory_search
+
+```javascript
+memory_search({
+  query: "authentication",
+  tags: ["security"],
+  limit: 10,
+  fuzzy: false
+})
+```
+
+### memory_recall
+
+```javascript
+memory_recall({
+  sessionId: "session-123"
+})
+```
+
+### memory_list
+
+```javascript
+memory_list({
+  status: "active",
+  tags: ["important"],
+  limit: 20
+})
+```
+
+### memory_graph
+
+```javascript
+memory_graph({
+  memoryId: "mem-123",
+  depth: 2
+})
+```

package/docs/CONFIG.md

@@ -0,0 +1,108 @@
+# Configuration - pi-recollect
+
+## Configuration File
+
+Create `pi-recollect.config.json`:
+
+```json
+{
+  "storage": {
+    "type": "sqlite",
+    "path": ".pi/memory.db",
+    "fts": true,
+    "ftsAlgorithm": "bm25"
+  },
+  "memory": {
+    "maxPerSession": 1000,
+    "defaultPriority": "normal",
+    "defaultExpires": "30d",
+    "autoArchive": true,
+    "archiveAfter": "90d"
+  },
+  "search": {
+    "defaultLimit": 20,
+    "fuzzyEnabled": true,
+    "fuzzyThreshold": 0.6,
+    "relevanceThreshold": 0.3
+  },
+  "decay": {
+    "enabled": true,
+    "highImportance": "never",
+    "normalImportance": "90d",
+    "lowImportance": "30d"
+  },
+  "graph": {
+    "enabled": true,
+    "maxDepth": 3
+  },
+  "session": {
+    "autoSave": true,
+    "saveInterval": 300000,
+    "maxSessions": 50
+  },
+  "context": {
+    "autoInject": true,
+    "maxMemories": 5,
+    "relevanceThreshold": 0.5
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PI_MEMORY_DB` | Database path | .pi/memory.db |
+| `PI_MEMORY_LIMIT` | Max memories | 1000 |
+
+## Storage
+
+### SQLite (Default)
+
+```json
+{
+  "storage": {
+    "type": "sqlite",
+    "path": ".pi/memory.db"
+  }
+}
+```
+
+### Memory Only
+
+```json
+{
+  "storage": {
+    "type": "memory"
+  }
+}
+```
+
+## Search Configuration
+
+```json
+{
+  "search": {
+    "fuzzyEnabled": true,
+    "fuzzyThreshold": 0.6,
+    "stemming": true,
+    "stopWords": ["the", "a", "an"]
+  }
+}
+```
+
+## Decay Configuration
+
+```json
+{
+  "decay": {
+    "enabled": true,
+    "schedule": "daily",
+    "thresholds": {
+      "high": 365,
+      "normal": 90,
+      "low": 30
+    }
+  }
+}
+```

package/docs/GUIDE.md

@@ -0,0 +1,148 @@
+# User Guide - pi-recollect
+
+## Overview
+
+pi-recollect provides persistent memory for Pi coding agents with SQLite storage and semantic search.
+
+## Memory Types
+
+### Simple Memory
+Basic key-value storage:
+
+```bash
+/memory store "Use feature flags for new features"
+```
+
+### Tagged Memory
+Categorized with tags:
+
+```bash
+/memory store "Use TypeScript strict mode" --tags=typescript,quality
+```
+
+### Priority Memory
+Important memories with high priority:
+
+```bash
+/memory store "CRITICAL: Database password exposed" --priority=high
+```
+
+### Expiring Memory
+Auto-delete after time:
+
+```bash
+/memory store "Temp: Fix expires in 1 hour" --expires=1h
+```
+
+## Search
+
+### Keyword Search
+```bash
+/memory search authentication
+```
+
+### Semantic Search
+```bash
+/memory search "user authentication best practices"
+```
+
+### Filtered Search
+```bash
+/memory search auth --tags=security --priority=high
+```
+
+### Fuzzy Search
+```bash
+/memory search "authentcation" --fuzzy
+```
+
+## Graph Memory
+
+### Relationships
+
+```bash
+/memory link mem-123 --to mem-456 --type="implements"
+```
+
+### Graph Query
+
+```bash
+/memory graph mem-123
+
+Output:
+## Memory Graph
+
+mem-123: "Auth middleware"
+├── implements → mem-456: "Auth interface"
+├── requires → mem-789: "JWT service"
+└── used-by → mem-111: "API routes"
+```
+
+## Memory Decay
+
+Old memories automatically age:
+
+| Age | Importance | Action |
+|-----|------------|--------|
+| < 1 week | High | Full relevance |
+| 1-4 weeks | Medium | Reduced relevance |
+| > 1 month | Low | Minimal relevance |
+| > 3 months | Very low | Archived |
+
+### Manual Decay
+
+```bash
+# Archive old memories
+/memory archive --older-than=30d
+
+# Restore archived
+/memory restore mem-123
+```
+
+## Session Continuity
+
+### Save Session
+
+```bash
+/memory save-session
+
+Output:
+## Session Saved
+
+Tasks completed: 5
+Key decisions: 3
+Open questions: 2
+Context size: 45KB
+```
+
+### Resume Session
+
+```bash
+/memory resume
+
+Output:
+## Resuming Session
+
+Last session: 2 hours ago
+Project: my-app
+Resuming: Task #6 of "Implement auth"
+```
+
+## Context Injection
+
+Memories automatically injected:
+
+```
+## Relevant Memories
+
+1. "Use auth middleware for /api routes" (from: Session 12)
+2. "JWT tokens in httpOnly cookie" (from: Session 8)
+```
+
+## Best Practices
+
+1. **Be specific** - Clear, actionable memories
+2. **Tag properly** - Easy retrieval later
+3. **Set priorities** - Important = high priority
+4. **Regular review** - Clean up old memories
+5. **Link related** - Build knowledge graph

package/docs/PATTERNS.md

@@ -0,0 +1,49 @@
+# Patterns Applied to pi-recollect
+
+This document lists all research patterns applied to this extension during development.
+
+## Research Sources
+
+- gstack (persistent daemon, design system, boil the lake)
+- gsd-2 (ADR, multi-model, branchless worktree)
+- pi-crew (hooks, metrics, correlation, UI patterns)
+- pi-hermes-memory (memory categories, learn command)
+- beads (hash IDs, graph memory, memory decay)
+- context-mode (BM25 search, context sandbox)
+- everything-claude-code (quality gates, agent shield)
+- vetc-dev-kit (SDLC router, systematic debugging)
+- caveman (token compression)
+- And more...
+
+## Patterns Implemented
+
+### Core Patterns
+
+| Pattern | Source | Description |
+|---------|--------|-------------|
+| GraphStore | beads | Hash-based ID graph with dependencies |
+| MemoryDecay | beads | Semantic summarization of old content |
+| ContextCompaction | oh-my-pi | Session compaction for long conversations |
+| HashIDs | beads | Conflict-free hash IDs |
+| MemoryCategories | pi-hermes-memory | Categorized memory storage |
+
+## Implementation Notes
+
+All patterns were researched from 52 source repositories and applied following the pi-crew delegation patterns skill.
+
+### Research Process
+
+1. Read source repositories (bare git repos in `source/`)
+2. Extract patterns applicable to this extension
+3. Implement patterns with tests
+4. Verify with 100% test coverage
+
+### Test Coverage
+
+All new patterns include comprehensive unit tests to ensure correctness.
+
+## References
+
+- [Research Index](../research-findings/00-index.md)
+- [API Reference](API.md)
+- [Quick Start](QUICKSTART.md)