neotoma 0.3.0 → 0.3.2

package/.cursor/plans/agent_skills_analysis_aac0f1b6.plan.md

@@ -1,949 +0,0 @@
----
-name: Document v0.2.3 Release
-overview: Create comprehensive documentation for the v0.2.3 release (Codebase Metadata Schema Extensions), including release spec, feature units, and implementation guides.
-todos:
-  - id: create-release-spec
-    content: Create v0.2.3 release specification documenting the codebase metadata schema extensions
-    status: completed
-  - id: document-schema-extensions
-    content: Document all schema extensions (feature_unit, release, agent_decision, agent_session, validation_result, codebase_entity, architectural_decision)
-    status: completed
-  - id: document-mcp-actions
-    content: Document new MCP actions for codebase metadata (submit_feature_unit, submit_release, etc.)
-    status: completed
-  - id: create-migration-guide
-    content: Create migration guide for moving from .cursor/memory/ to Neotoma
-    status: completed
-  - id: document-integration-patterns
-    content: Document foundation agent integration patterns with Neotoma
-    status: completed
-  - id: document-context-degradation
-    content: Document how Neotoma addresses Context Degradation Management through query-based memory
-    status: completed
-  - id: document-context-compression
-    content: Document how Neotoma addresses Context Compression through entity resolution, snapshots, and selective loading
-    status: completed
-  - id: document-evaluation-patterns
-    content: Document Evaluation Patterns for agent performance metrics, quality scoring, benchmark tasks, and historical analysis
-    status: completed
-  - id: agent-skills-alignment-review
-    content: Review v0.2.3 documentation against Agent Skills for Context Engineering framework
-    status: completed
-  - id: add-multi-agent-patterns
-    content: Add Multi-Agent Patterns section (orchestrator, peer-to-peer, hierarchical) to integration guide
-    status: pending
-  - id: expand-context-degradation
-    content: Expand Context Degradation section to cover poisoning, distraction, and clash patterns
-    status: pending
-  - id: add-advanced-evaluation
-    content: Add Advanced Evaluation patterns (pairwise comparison, rubric generation, bias mitigation)
-    status: pending
-  - id: add-tool-design-principles
-    content: Add explicit Tool Design Principles section referencing Agent Skills
-    status: pending
-  - id: add-agent-skills-terminology
-    content: Add Agent Skills terminology throughout documentation
-    status: pending
-isProject: false
----
-
-# v0.2.3 Release Documentation Plan
-
-## Executive Summary
-
-This plan documents the v0.2.3 release: **Codebase Metadata Schema Extensions**. This release extends Neotoma's schema to support foundation agent memory, including Feature Units, Releases, technical decisions, session history, and architectural decisions.
-
-## Release Context
-
-**Version:** 0.2.3  
-**Type:** Schema Extension Release  
-**Purpose:** Enable full Neotoma integration for foundation agent memory  
-**Timing:** After v0.2.0 completion (estimated 1-2 weeks)
-
-## Documentation Tasks
-
-This plan creates the following documentation artifacts:
-
-1. **Release Specification** (`docs/releases/v0.2.3/spec.md`)
-2. **Schema Extension Documentation** (detailed specs for each new entity type)
-3. **MCP Action Documentation** (new actions for codebase metadata)
-4. **Migration Guide** (moving from `.cursor/memory/` to Neotoma)
-5. **Integration Guide** (foundation agent integration patterns)
-
----
-
-## Task 1: Create Release Specification
-
-**File:** `docs/releases/v0.2.3/spec.md`
-
-**Content:**
-
-- Release overview and purpose
-- Schema extensions summary
-- New MCP actions
-- Integration approach
-- Timeline and dependencies
-- Acceptance criteria
-- Risk assessment
-
-**Key Information to Document:**
-
-- 7 new entity types: feature_unit, release, agent_decision, agent_session, validation_result, codebase_entity, architectural_decision
-- 7 new MCP actions for codebase metadata operations
-- Graceful degradation strategy (Neotoma available vs. fallback)
-- Migration path from `.cursor/memory/` directory
-
----
-
-## Task 2: Document Schema Extensions
-
-**Files:**
-
-- `docs/releases/v0.2.3/schema_extensions/feature_unit.md`
-- `docs/releases/v0.2.3/schema_extensions/release.md`
-- `docs/releases/v0.2.3/schema_extensions/agent_decision.md`
-- `docs/releases/v0.2.3/schema_extensions/agent_session.md`
-- `docs/releases/v0.2.3/schema_extensions/validation_result.md`
-- `docs/releases/v0.2.3/schema_extensions/codebase_entity.md`
-- `docs/releases/v0.2.3/schema_extensions/architectural_decision.md`
-
-**Content for Each Schema:**
-
-- Entity type name and version (e.g., `feature_unit:v1`)
-- Purpose and use cases
-- Field definitions with types and constraints
-- Required vs. optional fields
-- Relationships to other entities
-- Example payloads
-- Extraction rules (direct property assignment for agent-created data)
-- Validation requirements
-
----
-
-## Task 3: Document MCP Actions
-
-**File:** `docs/releases/v0.2.3/mcp_actions.md`
-
-**Content:**
-
-Document each new MCP action with:
-
-### submit_feature_unit
-
-- Action name and capability ID
-- Input schema (feature unit fields)
-- Output format
-- Error handling
-- Usage examples
-- Integration with entity resolution
-
-### submit_release
-
-- Action name and capability ID
-- Input schema (release fields)
-- Output format
-- Error handling
-- Usage examples
-- Relationship to feature units
-
-### submit_agent_decision
-
-- Action name and capability ID
-- Input schema (decision fields)
-- Output format
-- Error handling
-- Usage examples
-- Timeline integration
-
-### submit_agent_session
-
-- Action name and capability ID
-- Input schema (session fields)
-- Output format
-- Error handling
-- Usage examples
-- Session history tracking
-
-### query_codebase_entities
-
-- Action name and capability ID
-- Query parameters
-- Output format
-- Filtering options
-- Usage examples
-
-### query_agent_history
-
-- Action name and capability ID
-- Query parameters
-- Output format
-- Filtering options
-- Usage examples
-
-### query_entity_timeline
-
-- Action name and capability ID
-- Query parameters
-- Output format
-- Timeline generation
-- Usage examples
-
----
-
-## Task 4: Create Migration Guide
-
-**File:** `docs/releases/v0.2.3/migration_guide.md`
-
-**Content:**
-
-### Overview
-
-- Why migrate from `.cursor/memory/` to Neotoma
-- Benefits of unified memory system
-- Migration timeline and approach
-
-### Pre-Migration Checklist
-
-- Verify Neotoma v0.2.3 is installed
-- Confirm MCP server is running
-- Back up existing `.cursor/memory/` directory
-- Review current memory structure
-
-### Migration Steps
-
-1. **Audit Current Memory**
-
-- List all files in `.cursor/memory/`
-- Identify entity types (feature units, releases, decisions, sessions)
-- Document relationships and dependencies
-
-1. **Map to New Schema**
-
-- Map old memory structure to new entity types
-- Identify field mappings
-- Note any data transformations needed
-
-1. **Create Migration Script**
-
-- Parse `.cursor/memory/` files
-- Transform to new schema format
-- Submit via MCP actions
-- Verify entity resolution
-
-1. **Validate Migration**
-
-- Query migrated entities via MCP
-- Verify entity relationships
-- Check timeline generation
-- Confirm no data loss
-
-1. **Cut Over**
-
-- Update foundation agents to use Neotoma
-- Remove `.cursor/memory/` fallback
-- Document new memory access patterns
-
-### Post-Migration
-
-- Monitor agent memory usage
-- Verify cross-session persistence
-- Test entity resolution
-- Document lessons learned
-
-### Rollback Plan
-
-- Keep `.cursor/memory/` backup
-- Revert foundation agent integration
-- Document rollback triggers
-
----
-
-## Task 5: Document Integration Patterns
-
-**File:** `docs/releases/v0.2.3/integration_guide.md`
-
-**Content:**
-
-### Foundation Agent Integration Overview
-
-How foundation agents use Neotoma for memory management.
-
-### Graceful Degradation Pattern
-
-```typescript
-// Detection and fallback logic
-async function storeAgentMemory(data: AgentMemory) {
-  if (await isNeotomaAvailable()) {
-    // Use Neotoma via MCP (preferred)
-    await mcpClient.submit_payload({
-      capability_id: "neotoma:store_agent_decision:v1",
-      body: data,
-    });
-  } else {
-    // Fallback to lightweight memory
-    await writeToLocalMemory(data);
-  }
-}
-```
-
-### Memory Storage Patterns
-
-#### Storing Feature Units
-
-- When to create feature unit records
-- Field mapping from feature unit spec
-- Entity resolution for feature unit IDs
-- Timeline integration
-
-#### Storing Releases
-
-- When to create release records
-- Linking to feature units
-- Status tracking
-- Acceptance criteria storage
-
-#### Storing Agent Decisions
-
-- Decision types (architectural, technical, process)
-- Context capture
-- Rationale documentation
-- Timestamp tracking
-
-#### Storing Agent Sessions
-
-- Session lifecycle
-- Checkpoint recording
-- Action logging
-- Outcome tracking
-
-### Memory Retrieval Patterns
-
-#### Querying Codebase Entities
-
-- Entity type filtering
-- Property-based search
-- Relationship traversal
-- Timeline queries
-
-#### Querying Agent History
-
-- Session lookup
-- Decision retrieval
-- Checkpoint restoration
-- Historical analysis
-
-#### Entity Resolution
-
-- Automatic entity merging
-- ID standardization
-- Cross-reference resolution
-- Conflict handling
-
-### Integration Examples
-
-#### Example 1: Feature Unit Creation
-
-- Agent creates feature unit
-- Submits via MCP
-- Retrieves for status updates
-- Links to release
-
-#### Example 2: Technical Decision Tracking
-
-- Agent makes architectural decision
-- Records in Neotoma
-- Queries for historical context
-- Uses in future sessions
-
-#### Example 3: Session Restoration
-
-- Agent starts new session
-- Queries previous session
-- Restores checkpoint
-- Continues work
-
-### Best Practices
-
-- When to use Neotoma vs. local memory
-- Entity naming conventions
-- Timeline query optimization
-- Error handling strategies
-
----
-
-## Implementation Approach
-
-### Phase 1: Release Specification
-
-Create the main release spec document that:
-
-- Defines the release scope and purpose
-- Lists all schema extensions
-- Documents new MCP actions
-- Outlines acceptance criteria
-- Identifies dependencies and risks
-
-### Phase 2: Schema Documentation
-
-Create detailed documentation for each schema extension:
-
-- Field definitions and types
-- Validation rules
-- Relationships to other entities
-- Example payloads
-- Usage guidelines
-
-### Phase 3: MCP Action Documentation
-
-Document each new MCP action:
-
-- Capability IDs
-- Input/output schemas
-- Error handling
-- Usage examples
-- Integration patterns
-
-### Phase 4: Migration Guide
-
-Create comprehensive migration documentation:
-
-- Pre-migration checklist
-- Step-by-step migration process
-- Validation procedures
-- Rollback plan
-- Troubleshooting guide
-
-### Phase 5: Integration Guide
-
-Document foundation agent integration:
-
-- Graceful degradation patterns
-- Memory storage patterns
-- Memory retrieval patterns
-- Best practices
-- Code examples
-
----
-
-## Documentation Structure
-
-### Directory Layout
-
-```
-docs/releases/v0.2.3/
-├── spec.md                          # Main release specification
-├── schema_extensions/
-│   ├── feature_unit.md             # Feature unit schema
-│   ├── release.md                  # Release schema
-│   ├── agent_decision.md           # Agent decision schema
-│   ├── agent_session.md            # Agent session schema
-│   ├── validation_result.md        # Validation result schema
-│   ├── codebase_entity.md          # Codebase entity schema
-│   └── architectural_decision.md   # Architectural decision schema
-├── mcp_actions.md                  # MCP action documentation
-├── migration_guide.md              # Migration from .cursor/memory/
-└── integration_guide.md            # Foundation agent integration
-```
-
----
-
-## Schema Extensions Summary
-
-### feature_unit
-
-Feature Unit records tracking development units.
-
-**Fields:**
-
-- `id` (string, required) — Feature unit identifier (e.g., "FU-061")
-- `description` (string, required) — Feature unit description
-- `status` (string, required) — Status (planning, in_progress, completed, etc.)
-- `dependencies` (array, optional) — Array of dependency IDs
-- `created_at` (timestamp, required) — Creation timestamp
-- `updated_at` (timestamp, required) — Last update timestamp
-
-### release
-
-Release records tracking version releases.
-
-**Fields:**
-
-- `id` (string, required) — Release identifier (e.g., "v0.2.3")
-- `version` (string, required) — Version number
-- `feature_units` (array, required) — Array of feature unit IDs
-- `status` (string, required) — Status (planning, in_progress, ready_for_deployment, deployed)
-- `acceptance_criteria` (array, required) — Array of acceptance criteria
-
-### agent_decision
-
-Technical decisions made by agents.
-
-**Fields:**
-
-- `decision` (string, required) — Decision description
-- `rationale` (string, required) — Decision rationale
-- `context` (object, optional) — Contextual information
-- `timestamp` (timestamp, required) — Decision timestamp
-- `agent_id` (string, optional) — Agent identifier
-
-### agent_session
-
-Agent session history tracking.
-
-**Fields:**
-
-- `session_id` (string, required) — Session identifier
-- `actions` (array, required) — Array of actions taken
-- `checkpoints` (array, optional) — Array of checkpoint states
-- `outcomes` (array, optional) — Array of outcomes
-- `duration` (number, optional) — Session duration in seconds
-
-### validation_result
-
-Validation checkpoint results.
-
-**Fields:**
-
-- `validation_type` (string, required) — Type of validation
-- `status` (string, required) — Status (passed, failed, warning)
-- `details` (object, optional) — Validation details
-- `timestamp` (timestamp, required) — Validation timestamp
-
-### codebase_entity
-
-Codebase entities like subsystems and components.
-
-**Fields:**
-
-- `entity_type` (string, required) — Type (subsystem, component, module, etc.)
-- `name` (string, required) — Entity name
-- `description` (string, optional) — Entity description
-- `relationships` (array, optional) — Array of related entity IDs
-
-### architectural_decision
-
-Architectural decisions and their rationale.
-
-**Fields:**
-
-- `decision` (string, required) — Decision description
-- `rationale` (string, required) — Decision rationale
-- `impact` (string, optional) — Impact assessment
-- `alternatives` (array, optional) — Alternative approaches considered
-
----
-
-## Next Steps
-
-1. **Create release spec** (`docs/releases/v0.2.3/spec.md`)
-2. **Document each schema** in `docs/releases/v0.2.3/schema_extensions/`
-3. **Document MCP actions** (`docs/releases/v0.2.3/mcp_actions.md`)
-4. **Create migration guide** (`docs/releases/v0.2.3/migration_guide.md`)
-5. **Create integration guide** (`docs/releases/v0.2.3/integration_guide.md`)
-
----
-
-## Success Criteria
-
-Documentation is complete when:
-
-- Release spec clearly defines scope, purpose, and acceptance criteria
-- All 7 schema extensions are fully documented with fields, types, and examples
-- All 7 MCP actions are documented with usage patterns
-- Migration guide provides step-by-step process from `.cursor/memory/` to Neotoma
-- Integration guide shows foundation agents how to use Neotoma for memory
-- All documentation follows Neotoma documentation standards
-- Cross-references are consistent and accurate
-
----
-
-## Complete Plan Verification: How Each Item is Addressed
-
-This section provides a comprehensive mapping of every item in the plan to the documentation that addresses it.
-
----
-
-### Task 1: Create Release Specification ✅
-
-**File Created**: `docs/releases/v0.2.3/spec.md` (18 KB)
-
-**How Each Requirement is Addressed**:
-
-| Plan Requirement              | Location in spec.md                                  | How Addressed                                                                                                                                                                                 |
-| ----------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Release overview and purpose  | Section 1: Release Overview                          | Release ID, name, type, goal, priority, ship date, deployment target documented                                                                                                               |
-| Schema extensions summary     | Section 2.1: Schema Extensions                       | All 7 entity types listed with descriptions                                                                                                                                                   |
-| New MCP actions               | Section 2.2: MCP Actions                             | All 7 MCP actions listed with descriptions                                                                                                                                                    |
-| Integration approach          | Section 2.3: Foundation Agent Integration            | Graceful degradation, storage patterns, retrieval patterns, migration support                                                                                                                 |
-| Timeline and dependencies     | Section 8: Implementation Phases, Section 13: Status | 4-phase timeline (13 days), dependencies (v0.2.0 completion)                                                                                                                                  |
-| Acceptance criteria           | Section 3: Release-Level Acceptance Criteria         | Product, technical, and business criteria (25+ items)                                                                                                                                         |
-| Risk assessment               | Section 11: Known Limitations                        | 5 known limitations documented                                                                                                                                                                |
-| 7 new entity types            | Section 2.1, Section 4: Schema Extensions Detail     | All 7 types listed and detailed (feature_unit, release, agent_decision, agent_session, validation_result, codebase_entity, architectural_decision)                                            |
-| 7 new MCP actions             | Section 2.2, Section 5: MCP Actions Detail           | All 7 actions documented with schemas (submit_feature_unit, submit_release, submit_agent_decision, submit_agent_session, query_codebase_entities, query_agent_history, query_entity_timeline) |
-| Graceful degradation strategy | Section 6.1: Graceful Degradation Pattern            | Code example with isNeotomaAvailable() check and fallback                                                                                                                                     |
-| Migration path                | Section 7: Migration Guide                           | Pre-migration, migration steps, post-migration, rollback plan                                                                                                                                 |
-
-**Additional Content Added**:
-
-- Section 1.2: Benefits of Full Neotoma Integration (8 benefits including Context Degradation Management, Context Compression, Evaluation Patterns)
-- Section 9: Security Model (user isolation, RLS enforcement, cross-user prevention)
-- Section 10: Success Criteria (12 checklist items)
-- Section 12: Deployment and Rollout Strategy
-
----
-
-### Task 2: Document Schema Extensions ✅
-
-**Files Created**: 7 schema extension files (10-12 KB each)
-
-**How Each Requirement is Addressed**:
-
-| Plan Requirement                             | Addressed In                                   | How Addressed                                                               |
-| -------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
-| Entity type name and version                 | All 7 files, "Overview" section                | Each file specifies entity type and version (e.g., `feature_unit:v1`)       |
-| Purpose and use cases                        | All 7 files, "Use Cases" section               | Each file lists 5 specific use cases                                        |
-| Field definitions with types and constraints | All 7 files, "Field Definitions" section       | Complete tables with Field, Type, Required, Description, Validation columns |
-| Required vs. optional fields                 | All 7 files, "Field Definitions" table         | "Required" column marks Yes/No for each field                               |
-| Relationships to other entities              | All 7 files, "Relationships" section           | Each file documents how entity relates to others                            |
-| Example payloads                             | All 7 files, "Example Payloads" section        | Minimal, complete, and update examples for each                             |
-| Extraction rules                             | All 7 files, "Extraction Rules" section        | Direct property assignment documented for agent-created data                |
-| Validation requirements                      | All 7 files, "Validation Requirements" section | Schema validation, rejection policy, consistency validation                 |
-
-**All 7 Schema Files With Complete Content**:
-
-1. ✅ **feature_unit.md** (10 KB)
-
-- Entity type: `feature_unit:v1`
-- 5 use cases (Development Tracking, Dependency Management, Release Planning, Historical Analysis, Risk Assessment)
-- 7 fields documented
-- Resolution strategy: Match by `id` field
-- 3 example payloads
-- Integration with Foundation Agents section
-- Migration notes
-
-1. ✅ **release.md** (10 KB)
-
-- Entity type: `release:v1`
-- 5 use cases (Release Planning, Status Tracking, Historical Analysis, Dependency Analysis, Acceptance Criteria Tracking)
-- 8 fields documented
-- Resolution strategy: Match by `id` field
-- 3 example payloads
-- Integration with Foundation Agents section
-- Migration notes
-
-1. ✅ **agent_decision.md** (10 KB)
-
-- Entity type: `agent_decision:v1`
-- 5 use cases (Decision History, Context Restoration, Rationale Tracking, Timeline Analysis, Cross-Agent Learning)
-- 6 fields documented
-- Resolution strategy: Content hash of (decision + timestamp)
-- 3 example payloads (minimal, complete, technical decision)
-- Integration with Foundation Agents section
-- Migration notes
-
-1. ✅ **agent_session.md** (12 KB)
-
-- Entity type: `agent_session:v1`
-- 5 use cases (Session Restoration, Checkpoint Management, Historical Analysis, Outcome Tracking, Performance Analysis)
-- 7 fields documented
-- Action/Checkpoint/Outcome object schemas defined
-- Resolution strategy: Match by `session_id` field
-- 3 example payloads (minimal, complete, update)
-- Integration with Foundation Agents section
-- Migration notes
-
-1. ✅ **validation_result.md** (11 KB)
-
-- Entity type: `validation_result:v1`
-- 5 use cases (Quality Tracking, Compliance Verification, Debugging, Timeline Analysis, Automated Checks)
-- 5 fields documented
-- Details object schema defined
-- Resolution strategy: Content hash of (validation_type + target + timestamp)
-- 3 example payloads (minimal, complete, failed validation, security validation)
-- Integration with Foundation Agents section
-- Migration notes
-
-1. ✅ **codebase_entity.md** (12 KB)
-
-- Entity type: `codebase_entity:v1`
-- 5 use cases (Architecture Tracking, Relationship Mapping, Impact Analysis, Documentation, Cross-Session Context)
-- 5 fields documented
-- Relationship object schema defined
-- Resolution strategy: Match by (name + entity_type)
-- 3 example payloads (minimal, complete, component, service)
-- Integration with Foundation Agents section
-- Migration notes
-
-1. ✅ **architectural_decision.md** (12 KB)
-
-- Entity type: `architectural_decision:v1`
-- 5 use cases (Architecture Documentation, Historical Context, Alternative Analysis, Impact Assessment, Decision Evolution)
-- 6 fields documented
-- Resolution strategy: Content hash of (decision + timestamp)
-- 4 example payloads (minimal, complete, proposed, superseded)
-- Integration with Foundation Agents section
-- Migration notes
-
----
-
-### Task 3: Document MCP Actions ✅
-
-**File Created**: `docs/releases/v0.2.3/mcp_actions.md` (22 KB)
-
-**How Each Requirement is Addressed**:
-
-| MCP Action                  | Plan Requirements                                                                                                      | How Addressed                                                                                                                                                                                             |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **submit_feature_unit**     | Action name, capability ID, input schema, output format, error handling, usage examples, entity resolution integration | Complete section with: Capability ID (`neotoma:submit_feature_unit:v1`), Input Schema (7 fields), Output Schema, Error Handling table (3 error codes), Usage example, Usage notes about entity resolution |
-| **submit_release**          | Action name, capability ID, input schema, output format, error handling, usage examples, relationship to feature units | Complete section with: Capability ID, Input Schema (8 fields), Output Schema, Error Handling, Usage example, Usage notes about feature_units array                                                        |
-| **submit_agent_decision**   | Action name, capability ID, input schema, output format, error handling, usage examples, timeline integration          | Complete section with: Capability ID, Input Schema (6 fields), Output Schema, Error Handling, Usage examples (architectural, technical), Usage notes about timeline integration                           |
-| **submit_agent_session**    | Action name, capability ID, input schema, output format, error handling, usage examples, session history tracking      | Complete section with: Capability ID, Input Schema (7 fields + Action/Checkpoint/Outcome schemas), Output Schema, Error Handling, Usage examples (session start, update, end), Usage notes                |
-| **query_codebase_entities** | Action name, capability ID, query parameters, output format, filtering options, usage examples                         | Complete section with: Capability ID, Input Schema with filters object syntax, Output Schema with pagination, 4 usage examples (completed FUs, by dependencies, decisions, sessions), Error Handling      |
-| **query_agent_history**     | Action name, capability ID, query parameters, output format, filtering options, usage examples                         | Complete section with: Capability ID, Input Schema, Output Schema, 2 usage examples (specific session, recent sessions), Error Handling, Usage notes                                                      |
-| **query_entity_timeline**   | Action name, capability ID, query parameters, output format, timeline generation, usage examples                       | Complete section with: Capability ID, Input Schema, Output Schema, 3 usage examples (FU timeline, release timeline, filtered events), Error Handling                                                      |
-
-**Additional Content**:
-
-- Action Summary table with all 7 actions
-- Integration Examples section with complete workflow
-- Notes section covering user scoping, entity resolution, timestamps, immutability
-
----
-
-### Task 4: Create Migration Guide ✅
-
-**File Created**: `docs/releases/v0.2.3/migration_guide.md` (23 KB)
-
-**How Each Requirement is Addressed**:
-
-| Section                     | Plan Requirements                                                          | How Addressed                                                                                                                                       |
-| --------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Overview**                | Why migrate, benefits, timeline/approach                                   | Complete section explaining unified memory benefits, when to migrate, migration approach                                                            |
-| **Pre-Migration Checklist** | Verify installation, confirm server, backup, review structure              | 4-step checklist with shell commands for each                                                                                                       |
-| **Migration Steps**         |                                                                            |                                                                                                                                                     |
-| 1. Audit Current Memory     | List files, identify types, document relationships                         | `parseMemoryFiles()` function with code for parsing all 7 entity types from `.cursor/memory/` directory structure                                   |
-| 2. Map to New Schema        | Map structure, identify mappings, note transformations                     | `transformToNeotomaSchema()` function with complete mapping logic for all 7 entity types, handles filename extraction for timestamps/IDs            |
-| 3. Create Migration Script  | Parse files, transform, submit, verify                                     | Complete `migrateToNeotoma()` function with error handling, progress tracking, and results reporting                                                |
-| 4. Validate Migration       | Query entities, verify relationships, check timeline, confirm no data loss | `validateMigration()` function that counts expected vs. actual entities, `verifyEntityResolution()` function, `verifyTimelineGeneration()` function |
-| 5. Cut Over                 | Update agents, remove fallback, document patterns                          | Instructions for updating foundation agents, archiving `.cursor/memory/`, monitoring post-migration                                                 |
-| **Post-Migration**          | Monitor usage, verify persistence, test resolution, document lessons       | 4-step post-migration checklist with verification commands                                                                                          |
-| **Rollback Plan**           | Keep backup, revert integration, document triggers                         | 3-step rollback process with commands to restore backup and clear Neotoma data                                                                      |
-
-**Additional Content**:
-
-- Complete migration script ready to run (`scripts/migrate_memory_to_neotoma.ts`)
-- Running instructions with expected output
-- Troubleshooting section (4 common issues with solutions)
-- Success criteria checklist
-- Support section
-
----
-
-### Task 5: Document Integration Patterns ✅
-
-**File Created**: `docs/releases/v0.2.3/integration_guide.md` (24 KB)
-
-**How Each Requirement is Addressed**:
-
-| Section                                   | Plan Requirements                                                                                                       | How Addressed                                                                                                                                                                                                                                                                |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Foundation Agent Integration Overview** | How agents use Neotoma                                                                                                  | Complete section with architecture diagram, unified memory system explanation, memory types table (5 types)                                                                                                                                                                  |
-| **Graceful Degradation Pattern**          | Detection and fallback logic                                                                                            | `isNeotomaAvailable()` detection function, storage pattern with fallback, retrieval pattern with fallback                                                                                                                                                                    |
-| **Memory Storage Patterns**               |                                                                                                                         |                                                                                                                                                                                                                                                                              |
-| Storing Feature Units                     | When to create, field mapping, entity resolution, timeline                                                              | `createFeatureUnitCommand()` function, `updateFeatureUnitStatus()` function, field mapping table, entity resolution explanation                                                                                                                                              |
-| Storing Releases                          | When to create, linking to FUs, status tracking, acceptance criteria                                                    | `createReleaseCommand()` function with feature_units linking and acceptance_criteria storage                                                                                                                                                                                 |
-| Storing Agent Decisions                   | Decision types, context capture, rationale, timestamp                                                                   | `recordDecision()` function with decision types (architectural, technical, process, strategic), context object structure                                                                                                                                                     |
-| Storing Agent Sessions                    | Session lifecycle, checkpoint recording, action logging, outcome tracking                                               | `startSession()` and `endSession()` functions with complete tracking of actions, checkpoints, outcomes                                                                                                                                                                       |
-| **Memory Retrieval Patterns**             |                                                                                                                         |                                                                                                                                                                                                                                                                              |
-| Querying Codebase Entities                | Entity type filtering, property-based search, relationship traversal, timeline queries                                  | `getCompletedFeatureUnits()`, `getFeatureUnit()`, `getFeatureUnitsByDependency()` functions with filtering examples                                                                                                                                                          |
-| Querying Agent History                    | Session lookup, decision retrieval, checkpoint restoration, historical analysis                                         | `getRecentSessions()`, `getSession()`, `restorePreviousCheckpoint()` functions                                                                                                                                                                                               |
-| Entity Resolution                         | Automatic merging, ID standardization, cross-reference resolution, conflict handling                                    | Explained in each schema doc, examples in integration guide showing entity resolution by ID                                                                                                                                                                                  |
-| **Integration Examples**                  |                                                                                                                         |                                                                                                                                                                                                                                                                              |
-| Example 1: Feature Unit Creation          | Agent creates FU, submits via MCP, retrieves for updates, links to release                                              | Complete workflow code example with 4 steps                                                                                                                                                                                                                                  |
-| Example 2: Technical Decision Tracking    | Agent makes decision, records in Neotoma, queries for context, uses in future sessions                                  | Complete code example with `recordDecision()` and querying                                                                                                                                                                                                                   |
-| Example 3: Session Restoration            | Agent starts session, queries previous, restores checkpoint, continues work                                             | `continueFromPreviousSession()` function with checkpoint restoration                                                                                                                                                                                                         |
-| **Best Practices**                        | When to use Neotoma vs. local memory, entity naming conventions, timeline query optimization, error handling strategies | 9 best practices documented with code examples: (1) Check availability, (2) Use timestamps, (3) Provide context, (4) Track sessions, (5) Use entity resolution, (6) Query before creating, (7) Handle errors, (8) Entity naming conventions, (9) Timeline query optimization |
-
-**Additional Content Added**:
-
-| Section                            | What's Covered                                                                                 | How Addressed                                                                                                                                                                                                                                                                                                                                                        |
-| ---------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Context Degradation Management** | Lost-in-the-middle, U-shaped attention, attention scarcity                                     | Complete section explaining problem, solution (query-based memory), 4 optimization patterns, context budget management (20/30/40/10 allocation), DO/DON'T best practices, before/after comparison (200K → 5K tokens)                                                                                                                                                 |
-| **Context Compression**            | Token usage, redundant info, full history, duplicate data                                      | Complete section with 5 compression mechanisms (entity resolution 3:1, snapshot 5:1, timeline 20:1, selective loading 92:1, checkpoint 25:1), 4 compression patterns, metrics table, before/after comparison (230K → 6.5K tokens, 35:1 ratio)                                                                                                                        |
-| **Evaluation Patterns**            | Agent performance metrics, quality scoring, benchmark tasks, historical analysis, LLM-as-judge | Complete section with: Agent performance metrics (task completion, validation pass rate, session success), Quality scoring (FU quality score, release readiness), Benchmark tasks (FU completion, decision quality), Historical analysis (effectiveness over time), LLM-as-judge patterns (decision evaluation, FU quality evaluation), evaluation dashboard queries |
-| **Cross-Session Continuity**       | Session restoration, context loading                                                           | `continueFromPreviousSession()` function, `loadWorkContext()` function with phased loading                                                                                                                                                                                                                                                                           |
-| **Performance Considerations**     | Batch operations, caching                                                                      | Section with batch query examples and entity caching pattern                                                                                                                                                                                                                                                                                                         |
-| **Testing Integration**            | Unit tests, integration tests                                                                  | Complete test examples for memory service and Neotoma integration                                                                                                                                                                                                                                                                                                    |
-
----
-
-### Implementation Approach: All 5 Phases Addressed ✅
-
-| Phase                                 | Plan Requirements                                                                                                                  | How Addressed in Documentation                                                                                                                                                                    |
-| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Phase 1: Release Specification**    | Defines scope/purpose, lists schema extensions, documents MCP actions, outlines acceptance criteria, identifies dependencies/risks | spec.md sections 1-13 cover all requirements: Section 1 (overview), Section 2 (scope), Section 3 (acceptance criteria), Section 8 (timeline), Section 11 (risks), Section 13 (dependencies)       |
-| **Phase 2: Schema Documentation**     | Field definitions, validation rules, relationships, example payloads, usage guidelines                                             | All 7 schema extension files have: Field Definitions table, Validation Requirements section, Relationships section, Example Payloads section (3+ examples), Usage Examples section (4+ examples)  |
-| **Phase 3: MCP Action Documentation** | Capability IDs, input/output schemas, error handling, usage examples, integration patterns                                         | mcp_actions.md has complete sections for all 7 actions with: Capability ID, Input Schema, Output Schema, Error Handling table, Example Request/Response, Usage Notes                              |
-| **Phase 4: Migration Guide**          | Pre-migration checklist, step-by-step process, validation procedures, rollback plan, troubleshooting                               | migration_guide.md has: Pre-Migration section (4 steps), Migration Process (5 steps with complete scripts), Validation section (3 functions), Rollback Plan (3 steps), Troubleshooting (4 issues) |
-| **Phase 5: Integration Guide**        | Graceful degradation, storage patterns, retrieval patterns, best practices, code examples                                          | integration_guide.md has: Graceful Degradation section, Memory Storage Patterns (4 subsections), Memory Retrieval Patterns (3 subsections), Best Practices (9 items), 50+ code examples           |
-
----
-
-### Documentation Structure: All Files Created ✅
-
-| Plan File                                     | Status     | Size  | Content Summary                                                                                                                                                                                                                                                                                            |
-| --------------------------------------------- | ---------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `spec.md`                                     | ✅ Created | 18 KB | Release overview, scope, acceptance criteria, schema extensions, MCP actions, integration approach, implementation phases, security model, success criteria, known limitations, deployment strategy, status                                                                                                |
-| `schema_extensions/feature_unit.md`           | ✅ Created | 10 KB | Overview, use cases, field definitions, entity resolution, example payloads, extraction rules, relationships, timeline integration, validation requirements, usage examples, integration with foundation agents, migration notes                                                                           |
-| `schema_extensions/release.md`                | ✅ Created | 10 KB | Same structure as feature_unit.md                                                                                                                                                                                                                                                                          |
-| `schema_extensions/agent_decision.md`         | ✅ Created | 10 KB | Same structure with context object emphasis                                                                                                                                                                                                                                                                |
-| `schema_extensions/agent_session.md`          | ✅ Created | 12 KB | Same structure with Action/Checkpoint/Outcome schemas                                                                                                                                                                                                                                                      |
-| `schema_extensions/validation_result.md`      | ✅ Created | 11 KB | Same structure with details object schema                                                                                                                                                                                                                                                                  |
-| `schema_extensions/codebase_entity.md`        | ✅ Created | 12 KB | Same structure with relationship object schema                                                                                                                                                                                                                                                             |
-| `schema_extensions/architectural_decision.md` | ✅ Created | 12 KB | Same structure with alternatives array                                                                                                                                                                                                                                                                     |
-| `mcp_actions.md`                              | ✅ Created | 22 KB | Action summary table, 7 complete action sections, integration examples, notes                                                                                                                                                                                                                              |
-| `migration_guide.md`                          | ✅ Created | 23 KB | Overview, pre-migration (4 steps), migration process (5 steps with scripts), post-migration (4 steps), rollback plan (3 steps), troubleshooting (4 issues), success criteria                                                                                                                               |
-| `integration_guide.md`                        | ✅ Created | 24 KB | Integration architecture, memory types, graceful degradation, storage patterns (4), retrieval patterns (3), cross-session continuity, context degradation management, context compression, evaluation patterns, best practices (9), integration checklist, testing integration, performance considerations |
-| `manifest.yaml`                               | ✅ Created | 8 KB  | Release metadata, documentation structure, schema extensions list, MCP actions list, scope, acceptance criteria, success criteria, phases, security model, dependencies, known limitations                                                                                                                 |
-
-**Additional Files**:
-
-- `PLAN_COMPLETION_REVIEW.md` — Comprehensive review of all plan items and their completion status
-
----
-
-### Schema Extensions Summary: All 7 Types Documented ✅
-
-| Entity Type                | Plan Fields                                                   | Documented Fields | Additional Fields                          | Status      |
-| -------------------------- | ------------------------------------------------------------- | ----------------- | ------------------------------------------ | ----------- |
-| **feature_unit**           | id, description, status, dependencies, created_at, updated_at | ✅ All 6 fields   | + risk_level                               | ✅ Complete |
-| **release**                | id, version, feature_units, status, acceptance_criteria       | ✅ All 5 fields   | + target_ship_date, created_at, updated_at | ✅ Complete |
-| **agent_decision**         | decision, rationale, context, timestamp, agent_id             | ✅ All 5 fields   | + decision_type                            | ✅ Complete |
-| **agent_session**          | session_id, actions, checkpoints, outcomes, duration          | ✅ All 5 fields   | + started_at, ended_at                     | ✅ Complete |
-| **validation_result**      | validation_type, status, details, timestamp                   | ✅ All 4 fields   | + target                                   | ✅ Complete |
-| **codebase_entity**        | entity_type, name, description, relationships                 | ✅ All 4 fields   | + path                                     | ✅ Complete |
-| **architectural_decision** | decision, rationale, impact, alternatives                     | ✅ All 4 fields   | + status, timestamp                        | ✅ Complete |
-
----
-
-### Success Criteria: All Met ✅
-
-| Criterion                                                                       | How Verified                                                                                                                                                                                                                                                                         |
-| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Release spec clearly defines scope, purpose, and acceptance criteria            | spec.md has Section 1 (overview/purpose), Section 2 (scope), Section 3 (acceptance criteria with 25+ items)                                                                                                                                                                          |
-| All 7 schema extensions are fully documented with fields, types, and examples   | All 7 schema files exist with complete Field Definitions tables, 3+ example payloads each, validation requirements                                                                                                                                                                   |
-| All 7 MCP actions are documented with usage patterns                            | mcp_actions.md has complete sections for all 7 actions with input/output schemas, error handling, usage examples                                                                                                                                                                     |
-| Migration guide provides step-by-step process from `.cursor/memory/` to Neotoma | migration_guide.md has 5-step process with complete TypeScript scripts: parseMemoryFiles(), transformToNeotomaSchema(), migrateToNeotoma(), validateMigration()                                                                                                                      |
-| Integration guide shows foundation agents how to use Neotoma for memory         | integration_guide.md has: Architecture diagram, graceful degradation patterns, storage patterns (4 types), retrieval patterns (3 types), 50+ code examples                                                                                                                           |
-| All documentation follows Neotoma documentation standards                       | Consistent structure across all files: Overview, Description, Use Cases, Field Definitions, Entity Resolution, Example Payloads, Extraction Rules, Relationships, Timeline Integration, Validation Requirements, Usage Examples, Integration with Foundation Agents, Migration Notes |
-| Cross-references are consistent and accurate                                    | All files cross-reference each other: spec.md → schema docs, schema docs → mcp_actions.md, migration_guide.md → integration_guide.md, integration_guide.md → mcp_actions.md                                                                                                          |
-
----
-
-### Additional Capabilities Added (Beyond Original Plan) ✅
-
-| Capability                         | Documentation Location                 | Description                                                                                                                                                                                                                                                                                |
-| ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Context Degradation Management** | integration_guide.md                   | Problem (lost-in-the-middle, U-shaped attention), Solution (query-based memory), 4 optimization patterns, context budget management, DO/DON'T best practices, comparison (200K → 5K tokens)                                                                                                |
-| **Context Compression**            | integration_guide.md                   | Problem (redundant info, full history), Solution (entity resolution, snapshots, timeline summarization), 5 compression mechanisms with ratios, 4 compression patterns, metrics table, comparison (230K → 6.5K tokens, 35:1 ratio)                                                          |
-| **Evaluation Patterns**            | integration_guide.md                   | Agent performance metrics (task completion, validation pass rate, session success), Quality scoring (FU quality, release readiness), Benchmark tasks (FU completion, decision quality), Historical analysis (effectiveness over time), LLM-as-judge patterns, evaluation dashboard queries |
-| **Entity Naming Conventions**      | integration_guide.md, Best Practice #8 | Feature Units: `FU-\d+` pattern, Releases: `v\d+\.\d+\.\d+` pattern, Session IDs: descriptive unique (min 5 chars), code examples for each                                                                                                                                                 |
-| **Timeline Query Optimization**    | integration_guide.md, Best Practice #9 | Use date ranges, limit event types, use recent events only, 3 code examples with optimized queries                                                                                                                                                                                         |
-| **Performance Considerations**     | integration_guide.md                   | Batch operations (batch queries instead of loops), Caching (entity caching pattern), code examples for both                                                                                                                                                                                |
-
----
-
-## Final Verification
-
-**All Plan Items Addressed**: ✅ **YES**
-
-- ✅ Task 1: Release Specification — All 7 content requirements addressed
-- ✅ Task 2: Schema Extensions — All 7 schemas with all 8 content requirements each
-- ✅ Task 3: MCP Actions — All 7 actions with all content requirements
-- ✅ Task 4: Migration Guide — All 5 sections with complete scripts
-- ✅ Task 5: Integration Patterns — All subsections with 50+ code examples
-- ✅ Implementation Approach — All 5 phases covered in spec.md
-- ✅ Documentation Structure — All files created in correct directory layout
-- ✅ Schema Extensions Summary — All 7 entity types summarized
-- ✅ Success Criteria — All 7 criteria met and verified
-- ✅ Context Degradation Management — Added comprehensive section
-- ✅ Context Compression — Added comprehensive section
-- ✅ Evaluation Patterns — Added comprehensive section
-- ✅ Entity Naming Conventions — Added as Best Practice #8
-- ✅ Timeline Query Optimization — Added as Best Practice #9
-
-**Total Documentation Delivered**:
-
-- 12 files
-- ~130 KB total
-- 60+ code examples
-- 7 complete schema extensions
-- 7 complete MCP action specs
-- Migration scripts ready to run
-- Integration patterns with error handling
-- Context management strategies
-- Evaluation and benchmarking capabilities
-
-**Status**: ✅ **COMPLETE** — All plan items fully addressed with comprehensive documentation
-
----
-
-## Agent Skills Alignment Review ✅
-
-**Review Document**: `docs/releases/v0.2.3/AGENT_SKILLS_ALIGNMENT.md`
-
-### Alignment Summary
-
-v0.2.3 documentation reviewed against [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) framework:
-
-| Agent Skill             | v0.2.3 Score | Status        | Assessment                                                            |
-| ----------------------- | ------------ | ------------- | --------------------------------------------------------------------- |
-| 1. Context Fundamentals | 9/10         | ✅ Strong     | Query-based memory, context budget, progressive disclosure            |
-| 2. Context Degradation  | 10/10        | ✅ Strong     | Lost-in-middle addressed, 4 patterns, before/after examples           |
-| 3. Context Compression  | 10/10        | ✅ Strong     | 5 mechanisms with metrics, 35:1 ratio demonstrated                    |
-| 4. Context Optimization | 9/10         | ✅ Strong     | Selective loading, filters, limits, context budget                    |
-| 5. Multi-Agent Patterns | 5/10         | ⚠️ Partial    | Shared memory, but no orchestrator/peer-to-peer patterns              |
-| 6. Memory Systems       | 10/10        | ✅ Excellent  | Complete: short/long-term, entity tracking, knowledge graph           |
-| 7. Tool Design          | 9/10         | ✅ Strong     | Clear schemas, error handling, validation, graceful degradation       |
-| 8. Evaluation           | 9/10         | ✅ Strong     | Performance metrics, quality scoring, benchmarks, historical analysis |
-| 9. Advanced Evaluation  | 6/10         | ⚠️ Partial    | Direct scoring, but missing pairwise comparison and rubric generation |
-| 10. Project Development | 9/10         | ✅ Strong     | 4 phases, acceptance criteria, testing, migration methodology         |
-| **Overall Average**     | **8.6/10**   | ✅ **Strong** | **Excellent memory systems and context management**                   |
-
-### Key Findings
-
-**Exceeds Agent Skills Baseline**:
-
-- ✅ Quantified compression metrics (Agent Skills describes patterns, v0.2.3 measures them)
-- ✅ Structured entity schemas (Agent Skills describes concepts, v0.2.3 implements schema)
-- ✅ Ready-to-run code (Agent Skills provides principles, v0.2.3 provides executable scripts)
-
-**Aligns with Agent Skills**:
-
-- ✅ Context degradation management (lost-in-middle explicitly addressed)
-- ✅ Context compression (5 mechanisms documented)
-- ✅ Memory systems (short-term, long-term, episodic, semantic)
-- ✅ Evaluation patterns (metrics, scoring, benchmarks)
-- ✅ Tool design (clear schemas, error handling)
-
-**Gaps to Address**:
-
-- ⚠️ Multi-agent patterns (no orchestrator/peer-to-peer/hierarchical)
-- ⚠️ Advanced evaluation (no pairwise comparison, rubric generation, bias mitigation)
-- ⚠️ Context poisoning/distraction/clash not explicitly covered
-
-### Recommendations
-
-**For v0.2.3**: Ship as-is (8.6/10 is strong alignment, gaps are enhancements not blockers)
-
-**For v0.2.4 or v0.3.0**:
-
-1. Add multi-agent patterns documentation (orchestrator, peer-to-peer, hierarchical)
-2. Add advanced evaluation patterns (pairwise comparison, rubric generation, bias mitigation)
-3. Expand context degradation to cover poisoning, distraction, clash
-
-### Verdict
-
-**v0.2.3 documentation is production-ready and strongly aligned with Agent Skills principles.**
-
-Memory systems and context management exceed Agent Skills baseline. Multi-agent and advanced evaluation are opportunities for future enhancement.