Enhanced Project Context Detection for Memory System

[nikomatsakis]

Structured Insights and Project-Aware Memory System

Status: In Progress - Phase 2 Design Complete

Current Understanding

The current Hippo memory system uses abstract situational context which doesn't capture the rich contextual information needed for effective collaboration memory. We've evolved this into a structured insight format that combines automated project detection with conversational context capture.

New insight structure:

• project_details: Automatically populated by project detection system (Phase 1 ✅ complete)
• task: English description of what we were working on
• lead_in: What was being discussed when the insight emerged
• salient_quote: The key exchange or moment we want to remember
• importance: AI-assessed importance rating

This creates much richer, more actionable memory that captures both technical context and collaboration patterns.

Next Steps

• Implement new MCP tool interface for structured insights
• Update insight storage schema in Rust server
• Implement checkpoint consolidation process
• Update guidance.md with new checkpoint workflow
• Handle backward compatibility with existing insights
• Test the new structure with real collaboration sessions

Open Questions

• Should we migrate existing insights to new structure or maintain parallel systems?
• How should search work across the structured fields?
• Should we implement the salient quote approach for all insight types or just collaboration insights?

Context

This work emerged from analyzing the Sparkle collaborative memory framework and recognizing that effective memory needs to capture not just what happened, but the conversational dynamics and specific moments that reveal patterns. The structured format makes insights much more actionable for recreating collaborative states.

[nikomatsakis]

Session summary:

• Implemented Phase 1: Basic project detection system
• Created comprehensive design document with detection checklist and data structures
• Built Rust implementation with file system scanning, config file detection, and metadata extraction
• Successfully tested on Hippo project itself - correctly identifies as Polyglot Rust/Python project

Key accomplishments:

• ProjectDetector with configurable scanning (depth limits, skip directories)
• Detects 15+ config file types (Cargo.toml, pyproject.toml, package.json, etc.)
• Counts source file extensions to determine primary languages
• Extracts metadata from Cargo.toml and pyproject.toml
• Classifies projects as single language, polyglot, or documentation-focused
• Generates human-readable project summaries

Test results:

• Correctly detected Hippo as Polyglot Rust/Python project
• Found all key config files (Cargo.toml, pyproject.toml, book.toml)
• Extracted workspace members from Cargo.toml
• Extracted project name and description from pyproject.toml
• Counted 10 .rs files, 15 .py files, 26 .md files

Progress: Completed Phase 1 (Basic Detection). Ready to move to Phase 2 (Protocol Enhancement) or continue with git/README metadata extraction.

[nikomatsakis]

Checkpoint: Phase 1 Complete

Successfully implemented and tested the basic project detection system. Key deliverables:

Code Implementation:

• Complete with configurable scanning
• Support for 15+ config file types and source extensions
• Metadata extraction from Cargo.toml and pyproject.toml
• Smart project classification (single-language, polyglot, documentation)
• Comprehensive test suite validating functionality

Design Documentation:

• Detailed design document with detection checklist
• Clear data structures and integration points
• Performance considerations and error handling strategy

Validation:

• Successfully analyzed Hippo project (Polyglot Rust/Python)
• Extracted workspace structure and project metadata
• Generated meaningful project summaries

Next Phase Options:

1. Phase 2: Protocol integration (update MCP tools, storage schema)
2. Continue Phase 1: Add git/README metadata extraction
3. Phase 3: Enhanced search algorithms using project context

Phase 1 foundation is solid and ready for next steps. The checklist-based approach proved effective and extensible.

[nikomatsakis]

Phase 2 Design Plan - Checkpoint

Refined the protocol enhancement approach based on discussion:

Four-Part Context Structure:

1. Auto-detected directory summary (always generated)

   • "Polyglot Rust/Python project with mdbook docs, 10 .rs files, 15 .py files"
   • Provides structural/technical similarity matching

2. LLM technical stack description (always requested)

   • "AI memory system using Rust MCP server with Python components"
   • Handles planning phase where code doesn't exist yet
   • Semantic description of technical approach

3. LLM project purpose description (always requested)

   • "Collaborative memory system for AI development workflows"
   • High-level goal and domain context

4. LLM conversation situation (always requested)

   • "Implementing enhanced project context detection for better insight matching"
   • Current task/topic that gave rise to the insight

Implementation Approach:

• No caching initially - keep it simple
• No override logic - parallel context streams
• Search matches against all four with different weights
• Each provides different type of similarity (structural vs semantic)

MCP Tool Flow:

1. Run ProjectDetector on current directory
2. Ask LLM for three context descriptions
3. Store all four pieces in insight
4. Use all four for relevance matching

Next Steps:

• Update Insight storage schema
• Modify hippo_record_insight MCP tool
• Enhance search algorithm for multi-context matching
• Update guidance.md

This design handles both implemented projects and planning phases naturally.

[nikomatsakis]

Session summary:

• Implemented new structured insight format with project_details (auto-populated), task, lead_in, and salient_quote fields
• Updated MCP tool interfaces for hippo_record_insight, hippo_search_insights, and hippo_modify_insight
• Integrated project detection system to automatically populate project context
• Added checkpoint consolidation process to guidance.md
• Updated search engine to work with new structure (simplified version for now)

Impact on approach:

• Moved from abstract situational context to rich structured format that captures conversational dynamics
• Project detection provides automatic context without cognitive overhead
• Salient quotes preserve evidence and communication patterns for better collaboration continuity

Progress: Completed Phase 2 design and basic implementation. Next: test new structure with real usage and implement full embedding-based search across all structured fields.