gpt/README.md

aigpt

AI memory system with psychological analysis for Claude via MCP.

Current: Layers 1-4 Complete - Memory storage, AI interpretation, personality analysis, integrated profile, and relationship inference.

Planned: Layer 5 - Knowledge sharing platform combining useful insights with author personality.

Features

Layer 1: Pure Memory Storage

• 🗄️ SQLite Storage: Reliable database with ACID guarantees
• 🔖 ULID IDs: Time-sortable, 26-character unique identifiers
• 🔍 Search: Fast content-based search
• 📝 CRUD Operations: Complete memory management

Layer 2: AI Memory

• 🧠 AI Interpretation: Claude interprets and evaluates memories
• 📊 Priority Scoring: Importance ratings (0.0-1.0)
• 🎯 Smart Storage: Memory + evaluation in one step

Layer 3: Personality Analysis

• 🔬 Big Five Model: Scientifically validated personality assessment
• 📈 Pattern Recognition: Analyzes memory patterns to build user profile
• 💾 Historical Tracking: Save and compare analyses over time

Layer 3.5: Integrated Profile

• 🎯 Essential Summary: Unified view of personality, interests, and values
• 🤖 AI-Optimized: Primary tool for AI to understand the user
• ⚡ Smart Caching: Auto-updates only when necessary
• 🔍 Flexible Access: Detailed data still accessible when needed

Layer 4: Relationship Inference (Optional)

• 🤝 Relationship Tracking: Track interactions with entities (people, characters, etc.)
• 📊 Bond Strength: Infer relationship strength from memory patterns
• 🎮 Game Ready: Foundation for companion apps, games, VTubers
• 🔒 Opt-in: Enable only when needed with --enable-layer4 flag

Layer 5: Knowledge Sharing (Planned)

• 💡 Information + Personality: Share AI interactions with context
• 🌐 SNS for AI Era: Useful insights combined with author's unique perspective
• 🔒 Privacy-First: Share essence, not raw data
• 📊 Showcase: Display how AI understands you

General

• 🛠️ MCP Integration: Works seamlessly with Claude Code
• 🧪 Well-tested: Comprehensive test coverage
• 🚀 Simple & Fast: Minimal dependencies, pure Rust

Quick Start

Installation

# Build
cargo build --release

# Install (optional)
cp target/release/aigpt ~/.cargo/bin/

CLI Usage

# Create a memory
aigpt create "Remember this information"

# List all memories
aigpt list

# Search memories
aigpt search "keyword"

# Show statistics
aigpt stats

MCP Integration with Claude Code

# Add to Claude Code
claude mcp add aigpt /path/to/aigpt/target/release/aigpt server

MCP Tools

Layer 1: Basic Memory (6 tools)

• create_memory - Simple memory creation
• get_memory - Retrieve by ID
• list_memories - List all memories
• search_memories - Content-based search
• update_memory - Update existing memory
• delete_memory - Remove memory

Layer 2: AI Memory (1 tool)

• create_ai_memory - Create with AI interpretation and priority score

Layer 3: Personality Analysis (2 tools)

• save_user_analysis - Save Big Five personality analysis
• get_user_analysis - Retrieve latest personality profile

Layer 3.5: Integrated Profile (1 tool)

• get_profile - Primary tool: Get integrated user profile with essential summary

Layer 4: Relationship Inference (2 tools, requires --enable-layer4)

• get_relationship - Get inferred relationship with specific entity
• list_relationships - List all relationships sorted by bond strength

Usage Examples in Claude Code

Layer 1: Simple Memory

Remember that the project deadline is next Friday.

Claude will use create_memory automatically.

Layer 2: AI Memory with Evaluation

create_ai_memory({
  content: "Designed a new microservices architecture",
  ai_interpretation: "Shows technical creativity and strategic thinking",
  priority_score: 0.85
})

Layer 3: Personality Analysis

# After accumulating memories, analyze personality
save_user_analysis({
  openness: 0.8,
  conscientiousness: 0.7,
  extraversion: 0.4,
  agreeableness: 0.65,
  neuroticism: 0.3,
  summary: "High creativity and planning ability, introverted personality"
})

# Retrieve analysis
get_user_analysis()

Layer 3.5: Integrated Profile (Recommended)

# Get essential user profile - AI's primary tool
get_profile()

# Returns:
{
  "dominant_traits": [
    {"name": "openness", "score": 0.8},
    {"name": "conscientiousness", "score": 0.7},
    {"name": "extraversion", "score": 0.4}
  ],
  "core_interests": ["Rust", "architecture", "design", "system", "memory"],
  "core_values": ["simplicity", "efficiency", "maintainability"],
  "key_memory_ids": ["01H...", "01H...", ...],
  "data_quality": 0.85
}

Usage Pattern:

• AI normally uses get_profile() to understand the user
• For specific details, AI can call get_memory(id), list_memories(), etc.
• Profile auto-updates when needed (10+ memories, new analysis, or 7+ days)

Layer 4: Relationship Inference (Optional, requires --enable-layer4)

# Create memories with entity tracking
Memory::new_with_entities({
  content: "Had lunch with Alice",
  ai_interpretation: "Pleasant social interaction",
  priority_score: 0.7,
  related_entities: ["alice"]
})

# Get relationship inference
get_relationship({ entity_id: "alice" })

# Returns:
{
  "entity_id": "alice",
  "interaction_count": 15,
  "avg_priority": 0.75,
  "days_since_last": 2,
  "bond_strength": 0.82,
  "relationship_type": "close_friend",
  "confidence": 0.80
}

# List all relationships
list_relationships({ limit: 5 })

Relationship Types:

• close_friend (0.8+): Very strong bond
• friend (0.6-0.8): Strong connection
• valued_acquaintance (0.4-0.6, high priority): Important but not close
• acquaintance (0.4-0.6): Regular contact
• regular_contact (0.2-0.4): Occasional interaction
• distant (<0.2): Minimal connection

Starting the Server:

# Normal mode (Layer 1-3.5 only)
aigpt server

# With relationship features (Layer 1-4)
aigpt server --enable-layer4

Big Five Personality Traits

• Openness: Creativity, curiosity, openness to new experiences
• Conscientiousness: Organization, planning, reliability
• Extraversion: Social energy, assertiveness, outgoingness
• Agreeableness: Cooperation, empathy, kindness
• Neuroticism: Emotional stability (low = stable, high = sensitive)

Scores range from 0.0 to 1.0, where higher scores indicate stronger trait expression.

Storage Location

All data stored in: ~/.config/syui/ai/gpt/memory.db

Architecture

Multi-layer system design:

• Layer 1 ✅ Complete: Pure memory storage (with entity tracking)
• Layer 2 ✅ Complete: AI interpretation with priority scoring
• Layer 3 ✅ Complete: Big Five personality analysis
• Layer 3.5 ✅ Complete: Integrated profile (unified summary)
• Layer 4 ✅ Complete: Relationship inference (optional, --enable-layer4)
• Layer 4+ 🔵 Planned: Extended game/companion features
• Layer 5 🔵 Planned: Knowledge sharing (information + personality)

Design Philosophy:

• "Internal complexity, external simplicity": Simple API, complex internals
• "AI judges, tool records": AI makes decisions, tool stores data
• Layered architecture: Each layer independent but interconnected
• Optional features: Core layers always active, advanced layers opt-in

See docs/ARCHITECTURE.md for details.

Documentation

• Architecture - Multi-layer system design
• Layer 1 Details - Technical details of memory storage
• Old Versions - Previous documentation

Development

# Run tests
cargo test

# Build for release
cargo build --release

# Run with verbose logging
RUST_LOG=debug aigpt server

Design Philosophy

"AI evolves, tools don't" - This tool provides simple, reliable storage while AI (Claude) handles interpretation, evaluation, and analysis. The tool focuses on being maintainable and stable.

License

MIT

Author

syui