@sashabogi/foundation 2.0.1 → 2.1.0

package/README.md

@@ -1,16 +1,6 @@
-<p align="center">
-  <img src="docs/foundation-banner.jpg" alt="Foundation - Unified MCP Server" width="100%">
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/@sashabogi/foundation"><img src="https://img.shields.io/npm/v/@sashabogi/foundation.svg" alt="npm version"></a>
-  <a href="https://www.npmjs.com/package/@sashabogi/foundation"><img src="https://img.shields.io/npm/dm/@sashabogi/foundation.svg" alt="npm downloads"></a>
-  <a href="https://github.com/sashabogi/foundation/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@sashabogi/foundation.svg" alt="license"></a>
-</p>
-
 # Foundation v2.0
 
-> **Production-grade MCP server for AI-assisted development with advanced memory**
+> **Production-grade MCP server for AI-assisted development**
 >
 > *"The future is not fixed, but it can be guided."* — Hari Seldon
 
@@ -153,7 +143,6 @@ gaia_save({
   tags: ["auth", "jwt", "security"],
   related_files: ["src/auth/jwt.ts"]
 })
-// Returns: { success: true, memory: { id: "mem_abc123", ... } }
 ```
 
 ### 3. Search Memories
@@ -164,7 +153,6 @@ gaia_search({
   tiers: ["project", "global"],
   limit: 10
 })
-// Returns ranked results with BM25 + composite scoring
 ```
 
 ### 4. Link Memories
@@ -177,7 +165,6 @@ gaia_link({
 })
 
 gaia_graph({ memory_id: "mem_impl_456" })
-// Returns: { depends_on: [{ id: "mem_decision_123", content: "...", ... }] }
 ```
 
 ---
@@ -254,9 +241,9 @@ Gaia provides **workflow patterns and persistent memory**. Version 2.0 transform
 - Searching past conversations
 - Capturing patterns and learnings
 
-**Tools (19 total):**
+**Tools (20 total):**
 
-#### Workflow Tools (12)
+#### Workflow Tools (9)
 ```
 gaia_checkpoint       // Save structured session state
 gaia_status          // Lightweight index card (~150 tokens)
@@ -264,9 +251,6 @@ gaia_query           // Keyword search checkpoint
 gaia_get_decisions   // List architectural decisions
 gaia_get_progress    // Task progress summary
 gaia_get_changes     // Files changed
-gaia_handoff         // Create session handoff document (NEW v2.0)
-gaia_observe         // Auto-detect patterns and observations (NEW v2.0)
-gaia_migrate         // Migrate v1 checkpoint data to v2 (NEW v2.0)
 gaia_learn           // Record correction for CLAUDE.md
 gaia_apply           // Apply learnings to CLAUDE.md
 gaia_review          // Review learnings
@@ -377,30 +361,25 @@ Returns:
 Build **dependency graphs** across memories with 5 typed links:
 
 ```typescript
-// Save a decision
 const decision = gaia_save({
   tier: "project",
   content: "Decision: Use React 18 with TypeScript",
   tags: ["decision", "architecture"]
 })
 
-// Save an implementation
 const impl = gaia_save({
   tier: "project",
   content: "Implementation: Set up Vite with React 18 + TS",
   tags: ["implementation"]
 })
 
-// Link them
 gaia_link({
   from_memory_id: impl.memory.id,
   to_memory_id: decision.memory.id,
   link_type: "depends_on"
 })
 
-// Later - retrieve the graph
 gaia_graph({ memory_id: impl.memory.id })
-// Shows: implementation depends_on decision
 ```
 
 **Link Types:**
@@ -459,7 +438,6 @@ CREATE TABLE memory_links (
 ### Example 1: Building a Knowledge Base
 
 ```typescript
-// Save architectural decisions
 gaia_save({
   tier: "project",
   content: "Decision: Use PostgreSQL with Drizzle ORM for type safety",
@@ -468,7 +446,6 @@ gaia_save({
   metadata: { decision_type: "technical", impact: "high" }
 })
 
-// Save implementation details
 gaia_save({
   tier: "project",
   content: "PostgreSQL connection pool configured with max 20 connections",
@@ -476,7 +453,6 @@ gaia_save({
   related_files: ["src/db/index.ts"]
 })
 
-// Later - search your decisions
 gaia_search({
   query: "database PostgreSQL decision",
   tiers: ["project"],
@@ -487,14 +463,12 @@ gaia_search({
 ### Example 2: Cross-Prompt Dependencies
 
 ```typescript
-// Day 1: Make a decision
 const decision = gaia_save({
   tier: "project",
   content: "Decision: Use tRPC for type-safe API",
   tags: ["decision", "api"]
 })
 
-// Day 2: Implement it
 const impl = gaia_save({
   tier: "project",
   content: "Created tRPC router with user and auth procedures",
@@ -502,35 +476,29 @@ const impl = gaia_save({
   related_files: ["src/server/trpc.ts"]
 })
 
-// Link them
 gaia_link({
   from_memory_id: impl.memory.id,
   to_memory_id: decision.memory.id,
   link_type: "depends_on"
 })
 
-// Day 30: Review decision chain
 gaia_graph({ memory_id: impl.memory.id })
-// Shows the full dependency graph
 ```
 
 ### Example 3: Session Workflow
 
 ```typescript
-// Session start - load context
 gaia_search({
   query: "authentication JWT implementation",
   current_file: "src/auth/verify.ts"
 })
 
-// During session - save observations
 gaia_save({
   tier: "session",
   content: "Bug: JWT verification doesn't handle expired tokens gracefully",
   tags: ["bug", "jwt"]
 })
 
-// Session end - create checkpoint
 gaia_checkpoint({
   summary: "Fixed JWT token expiration handling",
   decisions: [{
@@ -546,127 +514,6 @@ gaia_checkpoint({
 })
 ```
 
-### Example 4: Session Handoff
-
-```typescript
-// At session end - create checkpoint
-gaia_checkpoint({
-  summary: "Implemented user authentication with JWT",
-  purpose: "Build secure auth system",
-  project: "acme-app",
-  decisions: [{
-    topic: "Authentication",
-    decision: "Use JWT with RS256",
-    rationale: "Industry standard, secure, stateless"
-  }],
-  progress: [{
-    task: "Implement login endpoint",
-    status: "completed"
-  }, {
-    task: "Add refresh token logic",
-    status: "in_progress"
-  }],
-  changes: [{
-    file: "src/auth/jwt.ts",
-    action: "created",
-    summary: "JWT token generation and verification"
-  }],
-  context: {
-    branch: "feat/auth",
-    openQuestions: [
-      "Should we implement refresh token rotation?",
-      "What expiration time for access tokens?"
-    ],
-    relevantFiles: ["src/auth/jwt.ts", "src/auth/middleware.ts"]
-  }
-})
-
-// Create handoff document for next session
-gaia_handoff({
-  next_steps: [
-    "Implement refresh token rotation strategy",
-    "Add rate limiting to login endpoint",
-    "Write integration tests for auth flow",
-    "Update API documentation with auth examples"
-  ],
-  context_notes: "Auth system nearly complete. Main work remaining is refresh token security and testing. Consider implementing exponential backoff on failed login attempts.",
-  include_memories: true,
-  memory_query: "authentication JWT security"
-})
-
-// Returns markdown document at ~/.foundation/handoffs/handoff-2026-02-16T10-30-00.md
-// Includes:
-// - Full checkpoint state (decisions, progress, changes)
-// - Relevant memories with BM25 ranking
-// - Next steps
-// - Context notes
-// - Links to related files
-```
-
-### Example 5: Autonomous Observation
-
-```typescript
-// System automatically detects patterns from session activity
-gaia_observe({
-  lookback_days: 30,
-  auto_save: true,
-  min_confidence: "medium"
-})
-
-// Returns analysis like:
-//
-// ## Observations Detected (6)
-//
-// 1. 🔴 **Repeated decision-making on: Authentication**
-//    - Evidence: 3 decisions made about Authentication in current session
-//    - Confidence: high
-//    - Saved: mem_obs_abc123
-//
-// 2. 🔴 **Task blockers detected**
-//    - Evidence: 2 blocked task(s): "Add rate limiting", "Write auth tests"
-//    - Confidence: high
-//    - Saved: mem_obs_def456
-//
-// 3. 🟡 **Frequent modifications to: src/auth/jwt.ts**
-//    - Evidence: 3 changes to src/auth/jwt.ts in current session
-//    - Confidence: medium
-//    - Saved: mem_obs_ghi789
-//
-// 4. 🟡 **Multiple open questions - potential knowledge gaps**
-//    - Evidence: 4 unresolved questions
-//    - Confidence: medium
-//    - Saved: mem_obs_jkl012
-//
-// 5. 🔴 **High activity in areas: authentication, security, jwt**
-//    - Evidence: Frequent tags in recent memories
-//    - Confidence: high
-//    - Saved: mem_obs_mno345
-//
-// 6. 🟡 **File created and deleted: src/temp/test.ts**
-//    - Evidence: May indicate trial-and-error or false start
-//    - Confidence: medium
-//    - Saved: mem_obs_pqr678
-
-// Observations are saved to 'observation' tier
-// Automatically enriched with metadata for pattern analysis
-// Can be searched like any other memory
-
-// Later - search observations
-gaia_search({
-  query: "blocked tasks authentication",
-  tiers: ["observation"],
-  limit: 5
-})
-```
-
-**Pattern types detected:**
-- Repeated topics (same decisions multiple times)
-- Task blockers (blocked status in progress)
-- Frequent file changes (same file modified 3+ times)
-- Knowledge gaps (multiple open questions)
-- Activity hotspots (frequent tags in recent memories)
-- Anti-patterns (created then deleted files)
-
 ---
 
 ## Performance
@@ -704,13 +551,11 @@ Database:
 **Optional:** Start using the new memory tools for persistent knowledge:
 
 ```typescript
-// v1.x approach (still works)
 gaia_checkpoint({
   summary: "Implemented auth",
   decisions: [...]
 })
 
-// v2.0 approach (recommended - searchable + persistent)
 gaia_save({
   tier: "project",
   content: "Auth implementation uses JWT with RS256",