sqlew 3.9.1 → 4.0.0

package/docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-sqlew (SQL Efficient Workflow) is an MCP server designed to achieve **72% token reduction** in context sharing between Claude Code sub-agents through intelligent database design and metadata-driven architecture.
+sqlew (SQL Efficient Workflow) is an MCP server designed to achieve **72% token reduction** in context sharing between Claude Code agents through intelligent database design and metadata-driven architecture. **Version 4.0.0** introduces a major schema refactoring with unified v4_ table prefix and action-based MCP tool architecture.
 
 ## Core Design Principles
 
@@ -10,639 +10,158 @@ sqlew (SQL Efficient Workflow) is an MCP server designed to achieve **72% token
 
 The 72% token reduction is achieved through five key strategies:
 
-#### ID-Based Normalization
-- Eliminate string duplication across all entities
-- Store strings once in master tables, reference by integer IDs
-- Example: "authentication" tag appears once, referenced by ID in all decisions
-
-#### Integer Enums
-- Replace string values with integers (1-4) for status, priority, message types
-- 70-75% reduction in enum-based fields
-- Status: 1=active, 2=deprecated, 3=draft
-- Priority: 1=low, 2=medium, 3=high, 4=critical
-- Message types: 1=decision, 2=warning, 3=request, 4=info
-- Change types: 1=created, 2=modified, 3=deleted
-
-#### Pre-Aggregated Views
-- 6 token-efficient views for common queries
-- Eliminate need for multiple joins in client code
-- Views: `tagged_decisions`, `active_context`, `layer_summary`, `recent_file_changes`, `tagged_constraints`
-- 85% reduction in complex aggregation queries
-
-#### Type-Based Table Separation
-- Separate tables for numeric vs string decision values
-- `decisions` table for string values
-- `decisions_numeric` table for numeric values
-- 50% storage efficiency gain for numeric values
-
-#### Automatic Cleanup
-- Triggers delete old messages (>24h) and file changes (>7 days)
-- Prevents database bloat and maintains query performance
-- Configurable retention periods via `clear_old_data` tool
+| Strategy | Description | Savings |
+|----------|-------------|---------|
+| **ID-Based Normalization** | Store strings once in master tables, reference by integer IDs | ~50% |
+| **Integer Enums** | Replace string values with integers (status, priority, etc.) | 70-75% |
+| **Pre-Aggregated Views** | Eliminate need for multiple joins in client code | ~85% |
+| **Type-Based Separation** | Separate tables for numeric vs string values | ~50% |
+| **Automatic Cleanup** | Prevent database bloat via triggers | N/A |
 
 ### 2. Metadata-Driven Classification
 
 sqlew organizes data through five metadata dimensions:
 
-#### Tags
-Flexible categorization for cross-cutting concerns:
-- Seeded tags: authentication, security, api, database, performance, caching, logging, error-handling, validation, testing
-- Support for custom tags via auto-registration
-- AND/OR search logic for complex queries
-
-#### Layers
-Standard architecture layer organization:
-- **presentation**: UI, API endpoints, views
-- **business**: Business logic, services, use cases
-- **data**: Repositories, database access
-- **infrastructure**: Configuration, external services
-- **cross-cutting**: Logging, security, utilities
-
-#### Scopes
-Module or component-level organization:
-- Auto-registered from decision metadata
-- Enables focused queries per module
-- Example: "user-service", "api-gateway", "auth-module"
-
-#### Versions
-Automatic version history tracking:
-- `decision_history` table records all changes
-- Timestamp-ordered version retrieval
-- Never lose historical context
-
-#### Priority
-Express importance levels:
-- **low**: Informational, non-critical
-- **medium**: Standard priority (default)
-- **high**: Important, requires attention
-- **critical**: Urgent, blocking issue
-
-### 3. Data Integrity
-
-#### Foreign Key Constraints
-- All relationships enforced via SQLite foreign keys
-- Cascade deletes maintain referential integrity
-- Prevents orphaned records
-
-#### Transaction Guarantees
-- ACID properties via SQLite transactions
-- WAL (Write-Ahead Logging) mode for concurrency
-- Busy timeout: 5000ms for multi-agent coordination
-
-#### Auto-Registration Pattern
-- Master records auto-created on first use
-- `INSERT OR IGNORE` for idempotent inserts
-- Simplifies tool implementation (no pre-checks needed)
-
-#### Many-to-Many Relationships
-- Junction tables: `decision_tags`, `decision_scopes`, `constraint_tags`
-- Automatic relationship management in tool handlers
-- Transactional consistency across related tables
-
-## Database Schema
-
-### Master Tables (Normalization Layer)
-
-#### agents
-```sql
-CREATE TABLE agents (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name TEXT UNIQUE NOT NULL
-);
-```
-Purpose: Normalize agent names
-
-#### files
-```sql
-CREATE TABLE files (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  path TEXT UNIQUE NOT NULL
-);
-```
-Purpose: Normalize file paths
-
-#### context_keys
-```sql
-CREATE TABLE context_keys (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  key_name TEXT UNIQUE NOT NULL
-);
-```
-Purpose: Normalize decision keys
-
-#### layers
-```sql
-CREATE TABLE layers (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name TEXT UNIQUE NOT NULL
-);
-```
-Purpose: Architecture layers (seeded with 5 standard layers)
-
-#### tags
-```sql
-CREATE TABLE tags (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name TEXT UNIQUE NOT NULL
-);
-```
-Purpose: Categorization tags (10 seeded, auto-expandable)
-
-#### scopes
-```sql
-CREATE TABLE scopes (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name TEXT UNIQUE NOT NULL
-);
-```
-Purpose: Module/component scopes
-
-#### constraint_categories
-```sql
-CREATE TABLE constraint_categories (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  name TEXT UNIQUE NOT NULL
-);
-```
-Purpose: Constraint types (performance, architecture, security)
-
-#### m_config
-```sql
-CREATE TABLE m_config (
-  key TEXT PRIMARY KEY,
-  value TEXT NOT NULL
-);
-```
-Purpose: Configuration storage (retention settings, task thresholds)
-- Populated from `.sqlew/config.toml` on startup
-- Accessible via MCP `config` tool
-- See [CONFIGURATION.md](CONFIGURATION.md) for details
+| Dimension | Purpose | Example |
+|-----------|---------|---------|
+| **Tags** | Flexible cross-cutting categorization | authentication, security, api |
+| **Layers** | Architecture layer organization (9 layers) | business, data, infrastructure |
+| **Scopes** | Module/component-level organization | user-service, api-gateway |
+| **Versions** | Automatic version history tracking | 1.0.0, 1.1.0 |
+| **Priority** | Importance levels (1-4) | low, medium, high, critical |
+
+### 3. Layer System (v4.0)
+
+9 layers organized by file requirement:
+
+**FILE_REQUIRED (6 layers):**
+- presentation, business, data, infrastructure, cross-cutting, documentation
+
+**FILE_OPTIONAL (3 layers):**
+- planning, coordination, review
+
+### 4. Data Integrity
+
+- **Foreign Key Constraints**: All relationships enforced via SQLite
+- **Transaction Guarantees**: ACID properties, WAL mode for concurrency
+- **Auto-Registration Pattern**: Master records auto-created on first use
+
+## Database Schema (v4.0)
+
+All tables use unified `v4_` prefix. For detailed schema, see `src/database/migrations/v4/`.
+
+### Master Tables (Normalization)
+
+| Table | Purpose |
+|-------|---------|
+| `v4_files` | Normalize file paths |
+| `v4_context_keys` | Normalize decision keys |
+| `v4_layers` | Architecture layers (9 seeded) |
+| `v4_tags` | Categorization tags (10 seeded, auto-expandable) |
+| `v4_scopes` | Module/component scopes |
+| `v4_constraint_categories` | Constraint types (performance, architecture, security) |
+| `v4_task_statuses` | Task status types (pending, in_progress, completed, blocked, on_hold) |
+| `v4_config` | Configuration storage |
 
 ### Transaction Tables (Core Data)
 
-#### decisions (String Values)
-```sql
-CREATE TABLE decisions (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  key_id INTEGER NOT NULL REFERENCES context_keys(id),
-  value TEXT NOT NULL,
-  agent_id INTEGER NOT NULL REFERENCES agents(id),
-  layer_id INTEGER REFERENCES layers(id),
-  version TEXT,
-  status INTEGER DEFAULT 1,
-  ts INTEGER DEFAULT (unixepoch()),
-  UNIQUE(key_id)
-);
-```
-Purpose: Store string-valued decisions
-
-#### decisions_numeric (Numeric Values)
-```sql
-CREATE TABLE decisions_numeric (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  key_id INTEGER NOT NULL REFERENCES context_keys(id),
-  value REAL NOT NULL,
-  agent_id INTEGER NOT NULL REFERENCES agents(id),
-  layer_id INTEGER REFERENCES layers(id),
-  version TEXT,
-  status INTEGER DEFAULT 1,
-  ts INTEGER DEFAULT (unixepoch()),
-  UNIQUE(key_id)
-);
-```
-Purpose: Store numeric-valued decisions (50% more efficient)
-
-#### decision_history
-```sql
-CREATE TABLE decision_history (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  key_id INTEGER NOT NULL REFERENCES context_keys(id),
-  value TEXT NOT NULL,
-  agent_id INTEGER NOT NULL REFERENCES agents(id),
-  version TEXT,
-  ts INTEGER DEFAULT (unixepoch())
-);
-```
-Purpose: Track version history for all decision changes
-
-#### agent_messages
-```sql
-CREATE TABLE agent_messages (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  from_agent_id INTEGER NOT NULL REFERENCES agents(id),
-  to_agent_id INTEGER REFERENCES agents(id),
-  msg_type INTEGER NOT NULL,
-  message TEXT NOT NULL,
-  priority INTEGER DEFAULT 2,
-  payload TEXT,
-  read INTEGER DEFAULT 0,
-  ts INTEGER DEFAULT (unixepoch())
-);
-```
-Purpose: Agent-to-agent messaging with priority and broadcast support
-
-#### file_changes
-```sql
-CREATE TABLE file_changes (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  file_id INTEGER NOT NULL REFERENCES files(id),
-  agent_id INTEGER NOT NULL REFERENCES agents(id),
-  change_type INTEGER NOT NULL,
-  layer_id INTEGER REFERENCES layers(id),
-  description TEXT,
-  ts INTEGER DEFAULT (unixepoch())
-);
-```
-Purpose: Track file modifications with layer assignment
-
-#### constraints
-```sql
-CREATE TABLE constraints (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  category_id INTEGER NOT NULL REFERENCES constraint_categories(id),
-  constraint_text TEXT NOT NULL,
-  priority INTEGER DEFAULT 2,
-  layer_id INTEGER REFERENCES layers(id),
-  created_by INTEGER REFERENCES agents(id),
-  is_active INTEGER DEFAULT 1,
-  ts INTEGER DEFAULT (unixepoch())
-);
-```
-Purpose: Track project constraints with priority
-
-### Token-Efficient Views
-
-#### tagged_decisions
-Pre-joins decisions with all metadata (tags, layers, scopes):
-```sql
-CREATE VIEW tagged_decisions AS
-SELECT
-  d.id,
-  ck.key_name,
-  d.value,
-  a.name as agent_name,
-  l.name as layer_name,
-  d.version,
-  d.status,
-  d.ts,
-  GROUP_CONCAT(DISTINCT t.name) as tags,
-  GROUP_CONCAT(DISTINCT s.name) as scopes
-FROM decisions d
-JOIN context_keys ck ON d.key_id = ck.id
-JOIN agents a ON d.agent_id = a.id
-LEFT JOIN layers l ON d.layer_id = l.id
-LEFT JOIN decision_tags dt ON d.id = dt.decision_id
-LEFT JOIN tags t ON dt.tag_id = t.id
-LEFT JOIN decision_scopes ds ON d.id = ds.decision_id
-LEFT JOIN scopes s ON ds.scope_id = s.id
-GROUP BY d.id;
-```
-
-#### active_context
-Recent active decisions (1 hour window):
-```sql
-CREATE VIEW active_context AS
-SELECT * FROM tagged_decisions
-WHERE status = 1 AND ts > unixepoch() - 3600;
-```
-
-#### layer_summary
-Per-layer aggregated statistics:
-```sql
-CREATE VIEW layer_summary AS
-SELECT
-  l.name as layer_name,
-  COUNT(DISTINCT d.id) as active_decisions,
-  COUNT(DISTINCT fc.id) as recent_file_changes,
-  COUNT(DISTINCT c.id) as active_constraints
-FROM layers l
-LEFT JOIN decisions d ON l.id = d.layer_id AND d.status = 1
-LEFT JOIN file_changes fc ON l.id = fc.layer_id AND fc.ts > unixepoch() - 3600
-LEFT JOIN constraints c ON l.id = c.layer_id AND c.is_active = 1
-GROUP BY l.id;
-```
-
-### Indexing Strategy
-
-Optimized indexes for common query patterns:
-
-```sql
-CREATE INDEX idx_decisions_status ON decisions(status);
-CREATE INDEX idx_decisions_layer ON decisions(layer_id);
-CREATE INDEX idx_decisions_ts_desc ON decisions(ts DESC);
-CREATE INDEX idx_messages_to_read ON agent_messages(to_agent_id, read);
-CREATE INDEX idx_messages_priority ON agent_messages(priority);
-CREATE INDEX idx_file_changes_ts_desc ON file_changes(ts DESC);
-CREATE INDEX idx_file_changes_layer ON file_changes(layer_id);
-CREATE INDEX idx_constraints_active ON constraints(is_active);
-CREATE INDEX idx_constraints_layer ON constraints(layer_id);
-```
-
-All time-based queries use descending indexes on `ts` for efficient recent-first retrieval.
-
-### Automatic Triggers
-
-#### cleanup_old_messages
-```sql
-CREATE TRIGGER cleanup_old_messages
-AFTER INSERT ON agent_messages
-BEGIN
-  DELETE FROM agent_messages
-  WHERE ts < unixepoch() - 86400;
-END;
-```
-Deletes messages older than 24 hours on every insert.
-
-#### cleanup_old_file_changes
-```sql
-CREATE TRIGGER cleanup_old_file_changes
-AFTER INSERT ON file_changes
-BEGIN
-  DELETE FROM file_changes
-  WHERE ts < unixepoch() - 604800;
-END;
-```
-Deletes file changes older than 7 days on every insert.
-
-#### record_decision_history
-```sql
-CREATE TRIGGER record_decision_history
-AFTER UPDATE ON decisions
-BEGIN
-  INSERT INTO decision_history (key_id, value, agent_id, version, ts)
-  VALUES (OLD.key_id, OLD.value, OLD.agent_id, OLD.version, OLD.ts);
-END;
-```
-Auto-records version history on decision updates.
+| Table | Purpose |
+|-------|---------|
+| `v4_decisions` | Store decisions with layer, status, version |
+| `v4_decision_history` | Version history for all decision changes |
+| `v4_decision_context` | Decision context (rationale, alternatives, tradeoffs) |
+| `v4_file_changes` | Track file modifications with layer |
+| `v4_constraints` | Project constraints with priority |
+| `v4_tasks` | Task management with kanban-style status |
+
+### Relationship Tables
+
+| Table | Purpose |
+|-------|---------|
+| `v4_decision_tags` | Decision ↔ Tags (many-to-many) |
+| `v4_decision_scopes` | Decision ↔ Scopes (many-to-many) |
+| `v4_task_file_links` | Task ↔ Files with action types |
+| `v4_task_dependencies` | Task dependencies with circular detection |
+
+### Pre-Aggregated Views
+
+| View | Purpose |
+|------|---------|
+| `v4_tagged_decisions` | Decisions with all metadata (tags, layers, scopes) |
+| `v4_layer_summary` | Per-layer aggregated statistics |
+| `v4_recent_file_changes` | Recent file changes with metadata |
+| `v4_tagged_constraints` | Constraints with category and layer |
+| `v4_task_board` | Kanban-style task view with dependencies |
 
 ## MCP Tool Architecture
 
-### Tool Categories
-
-1. **Context Management (6 tools)** - `src/tools/context.ts`
-2. **Messaging (3 tools)** - `src/tools/messaging.ts`
-3. **File Tracking (3 tools)** - `src/tools/files.ts`
-4. **Constraint Management (3 tools)** - `src/tools/constraints.ts`
-5. **Utilities (3 tools)** - `src/tools/utils.ts`
-
-### Implementation Patterns
-
-#### Auto-Registration Pattern
-All tools auto-register master records on first use:
-
-```typescript
-// Example: Auto-register agent
-const agentId = db.prepare(
-  `INSERT OR IGNORE INTO agents (name) VALUES (?)
-   RETURNING id`
-).get(agentName)?.id
-  || db.prepare(`SELECT id FROM agents WHERE name = ?`).get(agentName)!.id;
-```
-
-#### Transaction Pattern
-Multi-table operations wrapped in transactions:
-
-```typescript
-db.transaction(() => {
-  // Insert decision
-  const decisionId = insertDecision();
-
-  // Insert tags
-  for (const tag of tags) {
-    insertDecisionTag(decisionId, tag);
-  }
-
-  // Insert scopes
-  for (const scope of scopes) {
-    insertDecisionScope(decisionId, scope);
-  }
-})();
-```
-
-#### Error Handling Pattern
-Comprehensive error messages with context:
-
-```typescript
-try {
-  // Database operation
-} catch (err: any) {
-  throw new Error(`Failed to set decision: ${err.message}`);
-}
-```
+### Action-Based Tool System (v4.0)
+
+6 consolidated action-based MCP tools:
+
+| Tool | Purpose | Key Actions |
+|------|---------|-------------|
+| **decision** | Decision context management | set, get, list, search, versions |
+| **file** | File change tracking | record, get, check_lock |
+| **constraint** | Constraint management | add, get, deactivate |
+| **task** | Task management with dependencies | create, update, move, link, list |
+| **help** | Documentation queries | query_action, query_tool, workflow_hints |
+| **suggest** | Decision intelligence | by_key, by_tags, check_duplicate |
+
+All tools support `action: "help"` for in-tool documentation.
 
 ## Performance Characteristics
 
 ### Query Performance
 
-| Operation | Avg Time | Notes |
-|-----------|----------|-------|
-| set_decision | 2-5 ms | With tags and scopes |
-| get_context | 5-15 ms | Filtered query via view |
-| get_layer_summary | 3-8 ms | Pre-aggregated view |
-| get_stats | 10-20 ms | Multiple table counts |
-| send_message | 2-4 ms | Simple insert |
-| record_file_change | 2-4 ms | With layer |
+| Operation | Avg Time |
+|-----------|----------|
+| decision.set | 2-5 ms |
+| decision.get | 5-15 ms |
+| file.record | 2-4 ms |
+| task.create | 3-7 ms |
 
 ### Database Size
 
 - **Empty:** ~28 KB (schema + seed data)
-- **100 decisions:** ~45 KB
-- **1000 decisions:** ~180 KB
 - **Growth Rate:** ~140 bytes/decision (linear)
 
 ### Concurrent Access
 
-- **Tested:** 5 simultaneous agents
 - **WAL Mode:** Enabled for read/write concurrency
-- **Busy Timeout:** 5000ms for coordination
-- **Result:** No conflicts, proper isolation
-
-## Token Efficiency Examples
-
-### Example 1: Simple Decision
-
-**Traditional JSON (1000 tokens):**
-```json
-{
-  "key": "authentication_method",
-  "value": "JWT with refresh tokens",
-  "agent": "auth-agent",
-  "layer": "business",
-  "status": "active",
-  "tags": ["authentication", "security", "api"],
-  "scopes": ["user-service", "api-gateway"],
-  "version": "1.0.0",
-  "updated": "2025-01-10T12:00:00Z"
-}
-```
-
-**sqlew Response (280 tokens):**
-```json
-{
-  "key_id": 42,
-  "value": "JWT with refresh tokens",
-  "agent_id": 5,
-  "layer_id": 2,
-  "status": 1,
-  "tag_ids": [1,4,5],
-  "scope_ids": [3,7],
-  "version": "1.0.0",
-  "ts": 1736510400
-}
-```
-
-**Savings: 720 tokens (72%)**
-
-### Example 2: Layer Summary
-
-**Traditional Approach (5000 tokens):**
-- Query all decisions, filter by layer
-- Query all file changes, filter by layer
-- Query all constraints, filter by layer
-- Aggregate in client code
-
-**sqlew Response (1400 tokens):**
-```json
-{
-  "layers": [
-    {"layer": "business", "decisions": 15, "files": 3, "constraints": 2},
-    {"layer": "data", "decisions": 8, "files": 1, "constraints": 1}
-  ]
-}
-```
-
-**Savings: 3600 tokens (72%)**
-
-## Deployment Considerations
-
-### Database Location
-
-Default: `.sqlew/sqlew.db` (project-local)
-
-Custom path via command-line:
-```bash
-npx sqlew /path/to/database.db
-```
-
-### Backup Strategy
-
-Regular backups recommended:
-```bash
-sqlite3 .sqlew/sqlew.db ".backup backup-$(date +%Y%m%d).db"
-```
-
-### Maintenance
-
-Periodic VACUUM to reclaim space:
-```bash
-sqlite3 .sqlew/sqlew.db "VACUUM;"
-```
-
-### Monitoring
-
-Track database size and query performance:
-```bash
-# Database size
-ls -lh .sqlew/sqlew.db
-
-# Query statistics via get_stats tool
-```
-
-## Extension Points
-
-### Adding Custom Tags
-
-Tags auto-register on first use - no schema changes needed:
-```typescript
-{
-  key: "feature_x",
-  value: "enabled",
-  tags: ["custom-tag-1", "custom-tag-2"]
-}
-```
-
-### Adding Custom Scopes
-
-Scopes auto-register like tags:
-```typescript
-{
-  key: "config_x",
-  value: "value",
-  scopes: ["new-module", "new-component"]
-}
-```
-
-### Adding Custom Metadata
-
-Extend schema with new master tables following the same pattern:
-1. Create master table for new dimension
-2. Create junction table for many-to-many
-3. Add to relevant views
-4. Update tool handlers
+- **Busy Timeout:** 5000ms
+
+## File Structure
+
+| Component | Location |
+|-----------|----------|
+| MCP Server | `src/index.ts` |
+| Database Init | `src/database/initialization/` |
+| Migrations | `src/database/migrations/v4/` |
+| Tool Implementations | `src/tools/` |
+| Types | `src/types.ts` |
+| Constants | `src/constants.ts` |
 
 ## Known Limitations
 
 1. **No Semantic Search:** Delegated to specialized tools like Serena
-2. **No Real-Time Notifications:** Polling-based messaging system
-3. **Single Project Scope:** Not multi-tenant
-4. **No Authentication:** Trust-based (local MCP server)
-5. **No Network Access:** Offline-only operation
-
-## Code Statistics
-
-- **Total Lines:** 3,424 TypeScript LOC
-- **Source Files:** 10
-- **Test Coverage:** 100% (all 18 tools verified)
-- **Type Safety:** Full TypeScript coverage
-
-### File Breakdown
-
-| Component | File | Lines |
-|-----------|------|-------|
-| MCP Server | src/index.ts | 821 |
-| Database | src/database.ts | 251 |
-| Schema | src/schema.ts | 203 |
-| Types | src/types.ts | 481 |
-| Constants | src/constants.ts | 277 |
-| Context Tools | src/tools/context.ts | 510 |
-| Messaging | src/tools/messaging.ts | 219 |
-| File Tracking | src/tools/files.ts | 255 |
-| Constraints | src/tools/constraints.ts | 242 |
-| Utilities | src/tools/utils.ts | 165 |
-
-## Future Enhancement Opportunities
-
-### Query Optimization
-- Materialized views for complex queries
-- Query result caching layer
-- Prepared statement pooling
-
-### Additional Metadata
-- Custom metadata fields via JSON columns
-- User-defined constraint categories
-- Dynamic tagging hierarchies
-
-### Export/Import
-- JSON export for decisions
-- Import from external sources
-- Backup/restore utilities
-
-### Analytics
-- Decision trend analysis
-- Agent activity metrics
-- Token savings tracking
-
-### Integration
-- WebSocket support for real-time updates
-- GraphQL API layer
-- REST API wrapper
-
-## Conclusion
-
-sqlew achieves its core design goal of **72% token reduction** through a combination of:
-- Intelligent database normalization
-- Metadata-driven organization
-- Pre-aggregated views
-- Automatic cleanup and history tracking
-
-The architecture balances efficiency, flexibility, and maintainability, providing a robust foundation for efficient multi-agent coordination in Claude Code projects.
+2. **Single Project Scope:** Not multi-tenant
+3. **No Authentication:** Trust-based (local MCP server)
+4. **No Network Access:** Offline-only operation
+
+## Version History
+
+| Version | Key Changes |
+|---------|-------------|
+| **v4.0.0** | Unified v4_ prefix, agent system removed, 6 action-based tools, 9 layers |
+| v3.9.0 | Decision Intelligence System, suggestion policies |
+| v3.8.0 | Layer expansion (5→9), file_actions parameter |
+| v3.0.0 | Kanban task system, 7-tool consolidation |
+| v2.0 | Action-based API, 96% token reduction |
+
+## Related Documentation
+
+- [SHARED_CONCEPTS.md](SHARED_CONCEPTS.md) - Common concepts across tools
+- [TOOL_REFERENCE.md](TOOL_REFERENCE.md) - Complete tool parameter reference
+- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options
+- [TASK_OVERVIEW.md](TASK_OVERVIEW.md) - Task management overview