vibeship-mind 5.0.1

Decision intelligence system for AI agents - hierarchical memory with outcome-weighted retrieval

Mind v5

Decision intelligence system for AI agents. Mind helps agents make better decisions over time by learning from outcomes.

Documentation

Guide	Description
Getting Started	15-minute setup guide
Core Concepts	Understanding memories, decisions, causality
User Guide	Step-by-step usage with examples
API Reference	Complete endpoint documentation
Installation	Production deployment options
Troubleshooting	Common issues and solutions

Core Concepts

• Hierarchical Temporal Memory: Memories exist at 4 levels (Working, Recent, Reference, Identity)
• Outcome-Weighted Salience: Memories that lead to good decisions become more prominent
• Decision Tracing: Every decision is tracked with the context that informed it
• Causal Learning: Understanding WHY decisions work, not just correlation
• Multi-Source Retrieval: Combines vector search, keywords, salience, recency, and causal signals

Quick Start

Option A: One-Command Install (Recommended)

# Install Mind
pip install vibeship-mind

# Setup and start (downloads PostgreSQL, pgvector automatically)
mind up

That's it! Mind will:

1. Download PostgreSQL binaries (no system install needed)
2. Download and install pgvector extension
3. Initialize the database
4. Start the API server on http://localhost:8001

Option B: With Existing PostgreSQL

# Install Mind
pip install vibeship-mind

# Configure your database
export MIND_DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mind

# Start server (skip automatic PostgreSQL setup)
mind serve

Option C: Docker Compose (Production)

# Copy environment config
cp .env.example .env

# Start all services (Postgres, NATS, Qdrant, API)
docker-compose up -d

# Check status
docker-compose ps

Verify It Works

# Run smoke test
pip install httpx
python scripts/smoke_test.py

Use the API

# Health check
curl http://localhost:8001/health

# Create a memory
curl -X POST http://localhost:8001/v1/memories/ \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "content": "User prefers concise code examples",
    "content_type": "preference",
    "temporal_level": 3,
    "salience": 0.8
  }'

# Retrieve memories (semantic search)
curl -X POST http://localhost:8001/v1/memories/retrieve \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "query": "code examples",
    "limit": 5
  }'

# Track a decision
curl -X POST http://localhost:8001/v1/decisions/track \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "session_id": "660e8400-e29b-41d4-a716-446655440001",
    "decision_type": "response_style",
    "decision_summary": "Used concise examples",
    "confidence": 0.85
  }'

# Record outcome
curl -X POST http://localhost:8001/v1/decisions/outcome \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "<trace_id_from_track>",
    "quality": 0.9,
    "signal": "explicit_positive",
    "feedback": "User understood quickly"
  }'

API Endpoints

Method	Endpoint	Description
GET	/health	Health check
POST	/v1/memories/	Create memory
GET	/v1/memories/{memory_id}	Get memory by ID
POST	/v1/memories/retrieve	Retrieve memories (semantic search)
POST	/v1/decisions/track	Track a decision
POST	/v1/decisions/outcome	Record decision outcome
GET	/metrics	Prometheus metrics

CLI Commands

Command	Description
mind up	One-command start: setup + serve
mind setup	Download PostgreSQL, pgvector, initialize database
mind serve	Start the API server
mind serve --reload	Start with auto-reload (development)
mind db init	Initialize database tables
mind db migrate	Run database migrations
mind health	Check service health
mind version	Show version information
mind mcp	Start MCP server for AI agents

Setup Options

mind setup --skip-postgres     # Use existing PostgreSQL
mind setup --skip-pgvector     # Skip pgvector installation
mind setup --skip-db-init      # Skip database initialization

Development

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/unit -v

# Start API in development mode
python -m mind.cli serve --reload

# Run linting
ruff check src/
mypy src/

Architecture

                         +------------------+
                         |    API Layer     |
                         |   (FastAPI)      |
                         +--------+---------+
                                  |
        +------------+------------+------------+------------+
        |            |            |            |            |
+-------v----+ +-----v------+ +---v----+ +----v-----+ +-----v------+
|  Memory    | |  Decision  | | Event  | | Causal   | | Retrieval  |
|  Service   | |  Service   | | Service| | Service  | | Service    |
+-------+----+ +-----+------+ +---+----+ +----+-----+ +-----+------+
        |            |            |            |            |
        +------------+------------+------------+------------+
                                  |
     +-------------+--------------+--------------+-------------+
     |             |              |              |             |
+----v----+  +-----v-----+  +-----v-----+  +-----v-----+  +----v----+
|Postgres |  |  Qdrant   |  |   NATS    |  | FalkorDB  |  | Temporal|
|(pgvector)|  | (vectors) |  | (events)  |  | (causal)  |  |(workflows)
+---------+  +-----------+  +-----------+  +-----------+  +---------+

Configuration

See .env.example for all configuration options.

License

MIT License - see LICENSE for details.

Links

• PyPI Package
• GitHub Repository
• Documentation