🧠 Ichiro-Mind

"The mind of Ichiro — Unifying all memory layers into one intelligent system."

Ichiro-Mind is the ultimate unified memory system for AI agents, combining the best of 5 proven memory approaches into one cohesive architecture. Named after its creator's vision for persistent, intelligent memory.

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    🧠 ICHIRO-MIND                               │
│              "The Mind That Never Forgets"                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ⚡ HOT LAYER (Working RAM)        🔥 WARM LAYER (Neural Net)   │
│  ┌─────────────────────┐          ┌─────────────────────┐       │
│  │ SESSION-STATE.md    │◄────────►│ Associative Memory  │       │
│  │ • Real-time state   │  Sync    │ • Spreading recall  │       │
│  │ • WAL protocol      │          │ • Causal chains     │       │
│  │ • Survives compact  │          │ • Contradiction det │       │
│  └─────────────────────┘          └─────────────────────┘       │
│           │                                │                    │
│           ▼                                ▼                    │
│  💾 COLD LAYER (Vectors)         📚 ARCHIVE LAYER (Long-term)   │
│  ┌─────────────────────┐          ┌─────────────────────┐       │
│  │ LanceDB Store       │          │ MEMORY.md + Daily   │       │
│  │ • Semantic search   │          │ • Git-Notes Graph   │       │
│  │ • Auto-extraction   │          │ • Cloud backup      │       │
│  │ • Importance score  │          │ • Human-readable    │       │
│  └─────────────────────┘          └─────────────────────┘       │
│                                                                 │
│  🧹 HYGIENE ENGINE              🎓 LEARNING ENGINE              │
│  • Auto-cleanup                 • Decision tracking             │
│  • Deduplication                • Error learning                │
│  • Token optimization           • Entity evolution              │
└─────────────────────────────────────────────────────────────────┘

✨ Core Features

1. Intelligent Memory Routing

Automatically selects the best retrieval method based on query type:

Query Type	Method	Speed
Recent context	HOT (SESSION-STATE)	<10ms
Facts & preferences	COLD (Vector search)	~50ms
Causal relationships	WARM (Neural graph)	~100ms
Long-term decisions	ARCHIVE (Git-Notes)	~200ms

2. Automatic Memory Lifecycle

Capture → Extract → Process → Store → Recall → Cleanup
   │          │         │        │       │        │
Input    Mem0/Auto   Importance  4-Layer  Smart   Periodic
Capture   Extraction   Scoring   Storage  Route   Hygiene

3. Neural Graph with Spreading Activation

• Not keyword search — Finds conceptually related memories through graph traversal
• 20 synapse types — Temporal, causal, semantic, emotional connections
• Hebbian learning — Memories strengthen with use
• Contradiction detection — Auto-detects conflicting information

4. Experience Learning

Decision → Action → Outcome → Lesson
    │         │        │         │
   Store    Track    Record    Learn

• Tracks decisions and their outcomes
• Learns from errors
• Suggests based on past patterns

5. Smart Hygiene

• Auto-cleans junk memories
• Deduplicates similar entries
• Optimizes token usage
• Monthly maintenance mode

🚀 Quick Start

Installation

clawhub install ichiro-mind

Setup

# Initialize Ichiro-Mind
ichiro-mind init

# Configure MCP
ichiro-mind setup-mcp

Basic Usage

from ichiro_mind import IchiroMind

# Initialize
mind = IchiroMind()

# Store memory (auto-routes to appropriate layer)
mind.remember(
    content="User prefers dark mode",
    category="preference",
    importance=0.9
)

# Recall with smart routing
result = mind.recall("What mode does user prefer?")

# Learn from experience
mind.learn(
    decision="Used SQLite for dev",
    outcome="slow_with_big_data",
    lesson="Use PostgreSQL for datasets >1GB"
)

📝 Memory Layers in Detail

HOT Layer — SESSION-STATE.md

Real-time working memory using Write-Ahead Log protocol.

# SESSION-STATE.md — Ichiro-Mind HOT Layer

## Current Task
Building unified memory system

## Active Context
- User: 兵步一郎
- Project: Ichiro-Mind
- Stack: Python + LanceDB + Neural Graph

## Key Decisions
- [x] Use 4-layer architecture
- [ ] Implement MCP interface

## Pending Actions
- [ ] Write SKILL.md
- [ ] Create Python core

WAL Protocol: Write BEFORE responding, not after.

WARM Layer — Neural Graph

Associative memory with spreading activation.

# Store with relationships
mind.remember(
    content="Use PostgreSQL for production",
    type="decision",
    tags=["database", "infrastructure"],
    relations=[
        {"type": "CAUSED_BY", "target": "performance_issues"},
        {"type": "LEADS_TO", "target": "better_scalability"}
    ]
)

# Deep recall
memories = mind.recall_deep(
    query="database decisions",
    depth=2  # Follow causal chains
)

COLD Layer — Vector Store

Semantic search with LanceDB.

# Auto-captured from conversation
mind.auto_capture(text="User likes minimal UI")

# Semantic search
results = mind.search("user interface preferences")

ARCHIVE Layer — Persistent Storage

Human-readable long-term memory.

workspace/
├── MEMORY.md              # Curated long-term
└── memory/
    ├── 2026-03-07.md      # Daily log
    ├── decisions/         # Structured decisions
    ├── entities/          # People, projects, concepts
    └── lessons/           # Learned experiences

🛠️ Advanced Features

Memory Hygiene

# Audit memory
ichiro-mind audit

# Clean junk
ichiro-mind cleanup --dry-run
ichiro-mind cleanup --confirm

# Optimize tokens
ichiro-mind optimize

Experience Replay

# Before making similar decision
similar = mind.get_lessons(context="database_choice")
# Returns past decisions and outcomes

Entity Tracking

# Track evolving entities
mind.track_entity(
    name="兵步一郎",
    type="person",
    attributes={
        "role": "creator",
        "interests": ["AI", "automation"],
        "preferences": {"ui": "minimal", "docs": "bilingual"}
    }
)

# Update entity
mind.update_entity("兵步一郎", {"last_contact": "2026-03-07"})

🔌 MCP Integration

Add to ~/.openclaw/mcp.json:

{
  "mcpServers": {
    "ichiro-mind": {
      "command": "python3",
      "args": ["-m", "ichiro_mind.mcp"],
      "env": {
        "ICHIRO_MIND_BRAIN": "default"
      }
    }
  }
}

📊 Performance

Operation	Latency	Throughput
HOT recall	<10ms	10K ops/s
WARM recall	~100ms	1K ops/s
COLD search	~50ms	500 ops/s
ARCHIVE read	~200ms	100 ops/s
Store memory	~20ms	5K ops/s

🎯 Use Cases

1. Long-running projects — Never lose context across sessions
2. Complex decisions — Track decision trees and outcomes
3. User relationships — Remember preferences, history, quirks
4. Error prevention — Learn from mistakes, suggest alternatives
5. Knowledge accumulation — Build up domain expertise over time

🧠 Philosophy

"Memory is not storage — it's intelligence."

Ichiro-Mind treats memory as a first-class citizen:

• Memories have relationships
• Memories evolve over time
• Memories compete for attention
• Memories decay when unused
• Contradictions are resolved

📚 Related Skills

• elite-longterm-memory — Foundation layer architecture
• neural-memory — Associative graph engine
• memory-hygiene — Cleanup and optimization
• memory-setup — Configuration and structure

🙏 Credits

Built by 兵步一郎 (Ichiro) with love for persistent, intelligent AI memory.

Inspired by the best memory systems in the OpenClaw ecosystem.

License

MIT