hindsight-api 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

hindsight_api/models.py

@@ -1,49 +1,47 @@
 """
 SQLAlchemy models for the memory system.
 """
+
 from datetime import datetime
-from typing import Optional
-from uuid import UUID as PyUUID, uuid4
+from uuid import UUID as PyUUID
 
+from pgvector.sqlalchemy import Vector
 from sqlalchemy import (
     CheckConstraint,
-    Column,
     Float,
     ForeignKey,
     ForeignKeyConstraint,
     Index,
     Integer,
-    PrimaryKeyConstraint,
     Text,
     func,
+)
+from sqlalchemy import (
     text as sql_text,
 )
 from sqlalchemy.dialects.postgresql import JSONB, TIMESTAMP, UUID
 from sqlalchemy.ext.asyncio import AsyncAttrs
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
-from pgvector.sqlalchemy import Vector
 
 
 class Base(AsyncAttrs, DeclarativeBase):
     """Base class for all models."""
+
     pass
 
 
 class Document(Base):
     """Source documents for memory units."""
+
     __tablename__ = "documents"
 
     id: Mapped[str] = mapped_column(Text, primary_key=True)
     bank_id: Mapped[str] = mapped_column(Text, primary_key=True)
-    original_text: Mapped[Optional[str]] = mapped_column(Text)
-    content_hash: Mapped[Optional[str]] = mapped_column(Text)
+    original_text: Mapped[str | None] = mapped_column(Text)
+    content_hash: Mapped[str | None] = mapped_column(Text)
     doc_metadata: Mapped[dict] = mapped_column("metadata", JSONB, server_default=sql_text("'{}'::jsonb"))
-    created_at: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
-    updated_at: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
+    created_at: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
 
     # Relationships
     memory_units = relationship("MemoryUnit", back_populates="document", cascade="all, delete-orphan")
@@ -56,45 +54,42 @@ class Document(Base):
 
 class MemoryUnit(Base):
     """Individual sentence-level memories."""
+
     __tablename__ = "memory_units"
 
     id: Mapped[PyUUID] = mapped_column(
         UUID(as_uuid=True), primary_key=True, server_default=sql_text("gen_random_uuid()")
     )
     bank_id: Mapped[str] = mapped_column(Text, nullable=False)
-    document_id: Mapped[Optional[str]] = mapped_column(Text)
+    document_id: Mapped[str | None] = mapped_column(Text)
     text: Mapped[str] = mapped_column(Text, nullable=False)
     embedding = mapped_column(Vector(384))  # pgvector type
-    context: Mapped[Optional[str]] = mapped_column(Text)
-    event_date: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), nullable=False)  # Kept for backward compatibility
-    occurred_start: Mapped[Optional[datetime]] = mapped_column(TIMESTAMP(timezone=True))  # When fact occurred (range start)
-    occurred_end: Mapped[Optional[datetime]] = mapped_column(TIMESTAMP(timezone=True))    # When fact occurred (range end)
-    mentioned_at: Mapped[Optional[datetime]] = mapped_column(TIMESTAMP(timezone=True))    # When fact was mentioned
+    context: Mapped[str | None] = mapped_column(Text)
+    event_date: Mapped[datetime] = mapped_column(
+        TIMESTAMP(timezone=True), nullable=False
+    )  # Kept for backward compatibility
+    occurred_start: Mapped[datetime | None] = mapped_column(
+        TIMESTAMP(timezone=True)
+    )  # When fact occurred (range start)
+    occurred_end: Mapped[datetime | None] = mapped_column(TIMESTAMP(timezone=True))  # When fact occurred (range end)
+    mentioned_at: Mapped[datetime | None] = mapped_column(TIMESTAMP(timezone=True))  # When fact was mentioned
     fact_type: Mapped[str] = mapped_column(Text, nullable=False, server_default="world")
-    confidence_score: Mapped[Optional[float]] = mapped_column(Float)
+    confidence_score: Mapped[float | None] = mapped_column(Float)
     access_count: Mapped[int] = mapped_column(Integer, server_default="0")
-    unit_metadata: Mapped[dict] = mapped_column("metadata", JSONB, server_default=sql_text("'{}'::jsonb"))  # User-defined metadata (str->str)
-    created_at: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
-    updated_at: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
+    unit_metadata: Mapped[dict] = mapped_column(
+        "metadata", JSONB, server_default=sql_text("'{}'::jsonb")
+    )  # User-defined metadata (str->str)
+    created_at: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
 
     # Relationships
     document = relationship("Document", back_populates="memory_units")
     unit_entities = relationship("UnitEntity", back_populates="memory_unit", cascade="all, delete-orphan")
     outgoing_links = relationship(
-        "MemoryLink",
-        foreign_keys="MemoryLink.from_unit_id",
-        back_populates="from_unit",
-        cascade="all, delete-orphan"
+        "MemoryLink", foreign_keys="MemoryLink.from_unit_id", back_populates="from_unit", cascade="all, delete-orphan"
     )
     incoming_links = relationship(
-        "MemoryLink",
-        foreign_keys="MemoryLink.to_unit_id",
-        back_populates="to_unit",
-        cascade="all, delete-orphan"
+        "MemoryLink", foreign_keys="MemoryLink.to_unit_id", back_populates="to_unit", cascade="all, delete-orphan"
     )
 
     __table_args__ = (
@@ -110,7 +105,7 @@ class MemoryUnit(Base):
             "(fact_type = 'opinion' AND confidence_score IS NOT NULL) OR "
             "(fact_type = 'observation') OR "
             "(fact_type NOT IN ('opinion', 'observation') AND confidence_score IS NULL)",
-            name="confidence_score_fact_type_check"
+            name="confidence_score_fact_type_check",
         ),
         Index("idx_memory_units_bank_id", "bank_id"),
         Index("idx_memory_units_document_id", "document_id"),
@@ -119,39 +114,46 @@ class MemoryUnit(Base):
         Index("idx_memory_units_access_count", "access_count", postgresql_ops={"access_count": "DESC"}),
         Index("idx_memory_units_fact_type", "fact_type"),
         Index("idx_memory_units_bank_fact_type", "bank_id", "fact_type"),
-        Index("idx_memory_units_bank_type_date", "bank_id", "fact_type", "event_date", postgresql_ops={"event_date": "DESC"}),
+        Index(
+            "idx_memory_units_bank_type_date",
+            "bank_id",
+            "fact_type",
+            "event_date",
+            postgresql_ops={"event_date": "DESC"},
+        ),
         Index(
             "idx_memory_units_opinion_confidence",
             "bank_id",
             "confidence_score",
             postgresql_where=sql_text("fact_type = 'opinion'"),
-            postgresql_ops={"confidence_score": "DESC"}
+            postgresql_ops={"confidence_score": "DESC"},
         ),
         Index(
             "idx_memory_units_opinion_date",
             "bank_id",
             "event_date",
             postgresql_where=sql_text("fact_type = 'opinion'"),
-            postgresql_ops={"event_date": "DESC"}
+            postgresql_ops={"event_date": "DESC"},
         ),
         Index(
             "idx_memory_units_observation_date",
             "bank_id",
             "event_date",
             postgresql_where=sql_text("fact_type = 'observation'"),
-            postgresql_ops={"event_date": "DESC"}
+            postgresql_ops={"event_date": "DESC"},
         ),
         Index(
             "idx_memory_units_embedding",
             "embedding",
             postgresql_using="hnsw",
-            postgresql_ops={"embedding": "vector_cosine_ops"}
+            postgresql_ops={"embedding": "vector_cosine_ops"},
         ),
     )
 
 
 class Entity(Base):
     """Resolved entities (people, organizations, locations, etc.)."""
+
     __tablename__ = "entities"
 
     id: Mapped[PyUUID] = mapped_column(
@@ -160,12 +162,8 @@ class Entity(Base):
     canonical_name: Mapped[str] = mapped_column(Text, nullable=False)
     bank_id: Mapped[str] = mapped_column(Text, nullable=False)
     entity_metadata: Mapped[dict] = mapped_column("metadata", JSONB, server_default=sql_text("'{}'::jsonb"))
-    first_seen: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
-    last_seen: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
+    first_seen: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
+    last_seen: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
     mention_count: Mapped[int] = mapped_column(Integer, server_default="1")
 
     # Relationships
@@ -175,13 +173,13 @@ class Entity(Base):
         "EntityCooccurrence",
         foreign_keys="EntityCooccurrence.entity_id_1",
         back_populates="entity_1",
-        cascade="all, delete-orphan"
+        cascade="all, delete-orphan",
     )
     cooccurrences_2 = relationship(
         "EntityCooccurrence",
         foreign_keys="EntityCooccurrence.entity_id_2",
         back_populates="entity_2",
-        cascade="all, delete-orphan"
+        cascade="all, delete-orphan",
     )
 
     __table_args__ = (
@@ -193,6 +191,7 @@ class Entity(Base):
 
 class UnitEntity(Base):
     """Association between memory units and entities."""
+
     __tablename__ = "unit_entities"
 
     unit_id: Mapped[PyUUID] = mapped_column(
@@ -214,6 +213,7 @@ class UnitEntity(Base):
 
 class EntityCooccurrence(Base):
     """Materialized cache of entity co-occurrences."""
+
     __tablename__ = "entity_cooccurrences"
 
     entity_id_1: Mapped[PyUUID] = mapped_column(
@@ -223,9 +223,7 @@ class EntityCooccurrence(Base):
         UUID(as_uuid=True), ForeignKey("entities.id", ondelete="CASCADE"), primary_key=True
     )
     cooccurrence_count: Mapped[int] = mapped_column(Integer, server_default="1")
-    last_cooccurred: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
+    last_cooccurred: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
 
     # Relationships
     entity_1 = relationship("Entity", foreign_keys=[entity_id_1], back_populates="cooccurrences_1")
@@ -241,6 +239,7 @@ class EntityCooccurrence(Base):
 
 class MemoryLink(Base):
     """Links between memory units (temporal, semantic, entity)."""
+
     __tablename__ = "memory_links"
 
     from_unit_id: Mapped[PyUUID] = mapped_column(
@@ -250,13 +249,11 @@ class MemoryLink(Base):
         UUID(as_uuid=True), ForeignKey("memory_units.id", ondelete="CASCADE"), primary_key=True
     )
     link_type: Mapped[str] = mapped_column(Text, primary_key=True)
-    entity_id: Mapped[Optional[PyUUID]] = mapped_column(
+    entity_id: Mapped[PyUUID | None] = mapped_column(
         UUID(as_uuid=True), ForeignKey("entities.id", ondelete="CASCADE"), primary_key=True
     )
     weight: Mapped[float] = mapped_column(Float, nullable=False, server_default="1.0")
-    created_at: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
+    created_at: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
 
     # Relationships
     from_unit = relationship("MemoryUnit", foreign_keys=[from_unit_id], back_populates="outgoing_links")
@@ -266,7 +263,7 @@ class MemoryLink(Base):
     __table_args__ = (
         CheckConstraint(
             "link_type IN ('temporal', 'semantic', 'entity', 'causes', 'caused_by', 'enables', 'prevents')",
-            name="memory_links_link_type_check"
+            name="memory_links_link_type_check",
         ),
         CheckConstraint("weight >= 0.0 AND weight <= 1.0", name="memory_links_weight_check"),
         Index("idx_memory_links_from", "from_unit_id"),
@@ -278,31 +275,22 @@ class MemoryLink(Base):
             "from_unit_id",
             "weight",
             postgresql_where=sql_text("weight >= 0.1"),
-            postgresql_ops={"weight": "DESC"}
+            postgresql_ops={"weight": "DESC"},
         ),
     )
 
 
 class Bank(Base):
     """Memory bank profiles with disposition traits and background."""
+
     __tablename__ = "banks"
 
     bank_id: Mapped[str] = mapped_column(Text, primary_key=True)
     disposition: Mapped[dict] = mapped_column(
-        JSONB,
-        nullable=False,
-        server_default=sql_text(
-            '\'{"skepticism": 3, "literalism": 3, "empathy": 3}\'::jsonb'
-        )
+        JSONB, nullable=False, server_default=sql_text('\'{"skepticism": 3, "literalism": 3, "empathy": 3}\'::jsonb')
     )
     background: Mapped[str] = mapped_column(Text, nullable=False, server_default="")
-    created_at: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
-    updated_at: Mapped[datetime] = mapped_column(
-        TIMESTAMP(timezone=True), server_default=func.now()
-    )
+    created_at: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(TIMESTAMP(timezone=True), server_default=func.now())
 
-    __table_args__ = (
-        Index("idx_banks_bank_id", "bank_id"),
-    )
+    __table_args__ = (Index("idx_banks_bank_id", "bank_id"),)

hindsight_api/pg0.py

@@ -1,12 +1,10 @@
 import asyncio
 import logging
-from typing import Optional
 
 from pg0 import Pg0
 
 logger = logging.getLogger(__name__)
 
-DEFAULT_PORT = 5555
 DEFAULT_USERNAME = "hindsight"
 DEFAULT_PASSWORD = "hindsight"
 DEFAULT_DATABASE = "hindsight"
@@ -17,34 +15,38 @@ class EmbeddedPostgres:
 
     def __init__(
         self,
-        port: int = DEFAULT_PORT,
+        port: int | None = None,
         username: str = DEFAULT_USERNAME,
         password: str = DEFAULT_PASSWORD,
         database: str = DEFAULT_DATABASE,
         name: str = "hindsight",
         **kwargs,
     ):
-        self.port = port
+        self.port = port  # None means pg0 will auto-assign
         self.username = username
         self.password = password
         self.database = database
         self.name = name
-        self._pg0: Optional[Pg0] = None
+        self._pg0: Pg0 | None = None
 
     def _get_pg0(self) -> Pg0:
         if self._pg0 is None:
-            self._pg0 = Pg0(
-                name=self.name,
-                port=self.port,
-                username=self.username,
-                password=self.password,
-                database=self.database,
-            )
+            kwargs = {
+                "name": self.name,
+                "username": self.username,
+                "password": self.password,
+                "database": self.database,
+            }
+            # Only set port if explicitly specified
+            if self.port is not None:
+                kwargs["port"] = self.port
+            self._pg0 = Pg0(**kwargs)
         return self._pg0
 
-    async def start(self, max_retries: int = 3, retry_delay: float = 2.0) -> str:
+    async def start(self, max_retries: int = 5, retry_delay: float = 4.0) -> str:
         """Start the PostgreSQL server with retry logic."""
-        logger.info(f"Starting embedded PostgreSQL (name: {self.name}, port: {self.port})...")
+        port_info = f"port={self.port}" if self.port else "port=auto"
+        logger.info(f"Starting embedded PostgreSQL (name={self.name}, {port_info})...")
 
         pg0 = self._get_pg0()
         last_error = None
@@ -53,9 +55,9 @@ class EmbeddedPostgres:
             try:
                 loop = asyncio.get_event_loop()
                 info = await loop.run_in_executor(None, pg0.start)
-                logger.info(f"PostgreSQL started on port {self.port}")
-                # Construct URI manually since pg0-embedded may return None
-                uri = info.uri if info and info.uri else f"postgresql://{self.username}:{self.password}@localhost:{self.port}/{self.database}"
+                # Get URI from pg0 (includes auto-assigned port)
+                uri = info.uri
+                logger.info(f"PostgreSQL started: {uri}")
                 return uri
             except Exception as e:
                 last_error = str(e)
@@ -68,8 +70,7 @@ class EmbeddedPostgres:
                     logger.debug(f"pg0 start attempt {attempt}/{max_retries} failed: {last_error}")
 
         raise RuntimeError(
-            f"Failed to start embedded PostgreSQL after {max_retries} attempts. "
-            f"Last error: {last_error}"
+            f"Failed to start embedded PostgreSQL after {max_retries} attempts. Last error: {last_error}"
         )
 
     async def stop(self) -> None:
@@ -91,9 +92,7 @@ class EmbeddedPostgres:
         pg0 = self._get_pg0()
         loop = asyncio.get_event_loop()
         info = await loop.run_in_executor(None, pg0.info)
-        # Construct URI manually since pg0-embedded may return None
-        uri = info.uri if info and info.uri else f"postgresql://{self.username}:{self.password}@localhost:{self.port}/{self.database}"
-        return uri
+        return info.uri
 
     async def is_running(self) -> bool:
         """Check if the PostgreSQL server is currently running."""
@@ -112,7 +111,7 @@ class EmbeddedPostgres:
         return await self.start()
 
 
-_default_instance: Optional[EmbeddedPostgres] = None
+_default_instance: EmbeddedPostgres | None = None
 
 
 def get_embedded_postgres() -> EmbeddedPostgres:

hindsight_api/server.py

@@ -6,6 +6,7 @@ This module provides the ASGI app for uvicorn import string usage:
 
 For CLI usage, use the hindsight-api command instead.
 """
+
 import os
 import warnings
 
@@ -29,15 +30,11 @@ config.configure_logging()
 _memory = MemoryEngine()
 
 # Create unified app with both HTTP and optionally MCP
-app = create_app(
-    memory=_memory,
-    http_api_enabled=True,
-    mcp_api_enabled=config.mcp_enabled,
-    mcp_mount_path="/mcp"
-)
+app = create_app(memory=_memory, http_api_enabled=True, mcp_api_enabled=config.mcp_enabled, mcp_mount_path="/mcp")
 
 
 if __name__ == "__main__":
     # When run directly, delegate to the CLI
     from hindsight_api.main import main
+
     main()

hindsight_api-0.1.7.dist-info/METADATA

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: hindsight-api
+Version: 0.1.7
+Summary: Hindsight: Agent Memory That Works Like Human Memory
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.17.1
+Requires-Dist: asyncpg>=0.29.0
+Requires-Dist: dateparser>=1.2.2
+Requires-Dist: fastapi[standard]>=0.120.3
+Requires-Dist: fastmcp>=2.3.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: greenlet>=3.2.4
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: langchain-text-splitters>=0.3.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-exporter-prometheus>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: pg0-embedded>=0.11.0
+Requires-Dist: pgvector>=0.4.1
+Requires-Dist: psycopg2-binary>=2.9.11
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentence-transformers<3.3.0,>=3.0.0
+Requires-Dist: sqlalchemy>=2.0.44
+Requires-Dist: tiktoken>=0.12.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: transformers<4.46.0,>=4.30.0
+Requires-Dist: uvicorn>=0.38.0
+Requires-Dist: wsproto>=1.0.0
+Provides-Extra: test
+Requires-Dist: filelock>=3.0.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-timeout>=2.4.0; extra == 'test'
+Requires-Dist: pytest-xdist>=3.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Hindsight API
+
+**Memory System for AI Agents** — Temporal + Semantic + Entity Memory Architecture using PostgreSQL with pgvector.
+
+Hindsight gives AI agents persistent memory that works like human memory: it stores facts, tracks entities and relationships, handles temporal reasoning ("what happened last spring?"), and forms opinions based on configurable disposition traits.
+
+## Installation
+
+```bash
+pip install hindsight-api
+```
+
+## Quick Start
+
+### Run the Server
+
+```bash
+# Set your LLM provider
+export HINDSIGHT_API_LLM_PROVIDER=openai
+export HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxxxxxx
+
+# Start the server (uses embedded PostgreSQL by default)
+hindsight-api
+```
+
+The server starts at http://localhost:8888 with:
+- REST API for memory operations
+- MCP server at `/mcp` for tool-use integration
+
+### Use the Python API
+
+```python
+from hindsight_api import MemoryEngine
+
+# Create and initialize the memory engine
+memory = MemoryEngine()
+await memory.initialize()
+
+# Create a memory bank for your agent
+bank = await memory.create_memory_bank(
+    name="my-assistant",
+    background="A helpful coding assistant"
+)
+
+# Store a memory
+await memory.retain(
+    memory_bank_id=bank.id,
+    content="The user prefers Python for data science projects"
+)
+
+# Recall memories
+results = await memory.recall(
+    memory_bank_id=bank.id,
+    query="What programming language does the user prefer?"
+)
+
+# Reflect with reasoning
+response = await memory.reflect(
+    memory_bank_id=bank.id,
+    query="Should I recommend Python or R for this ML project?"
+)
+```
+
+## CLI Options
+
+```bash
+hindsight-api --help
+
+# Common options
+hindsight-api --port 9000          # Custom port (default: 8888)
+hindsight-api --host 127.0.0.1     # Bind to localhost only
+hindsight-api --workers 4          # Multiple worker processes
+hindsight-api --log-level debug    # Verbose logging
+```
+
+## Configuration
+
+Configure via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_API_DATABASE_URL` | PostgreSQL connection string | `pg0` (embedded) |
+| `HINDSIGHT_API_LLM_PROVIDER` | `openai`, `groq`, `gemini`, `ollama` | `openai` |
+| `HINDSIGHT_API_LLM_API_KEY` | API key for LLM provider | - |
+| `HINDSIGHT_API_LLM_MODEL` | Model name | `gpt-4o-mini` |
+| `HINDSIGHT_API_HOST` | Server bind address | `0.0.0.0` |
+| `HINDSIGHT_API_PORT` | Server port | `8888` |
+
+### Example with External PostgreSQL
+
+```bash
+export HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@localhost:5432/hindsight
+export HINDSIGHT_API_LLM_PROVIDER=groq
+export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
+
+hindsight-api
+```
+
+## Docker
+
+```bash
+docker run --rm -it -p 8888:8888 \
+  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
+  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
+  ghcr.io/vectorize-io/hindsight:latest
+```
+
+## MCP Server
+
+For local MCP integration without running the full API server:
+
+```bash
+hindsight-local-mcp
+```
+
+This runs a stdio-based MCP server that can be used directly with MCP-compatible clients.
+
+## Key Features
+
+- **Multi-Strategy Retrieval (TEMPR)** — Semantic, keyword, graph, and temporal search combined with RRF fusion
+- **Entity Graph** — Automatic entity extraction and relationship tracking
+- **Temporal Reasoning** — Native support for time-based queries
+- **Disposition Traits** — Configurable skepticism, literalism, and empathy influence opinion formation
+- **Three Memory Types** — World facts, bank actions, and formed opinions with confidence scores
+
+## Documentation
+
+Full documentation: [https://hindsight.vectorize.io](https://hindsight.vectorize.io)
+
+- [Installation Guide](https://hindsight.vectorize.io/developer/installation)
+- [Configuration Reference](https://hindsight.vectorize.io/developer/configuration)
+- [API Reference](https://hindsight.vectorize.io/api-reference)
+- [Python SDK](https://hindsight.vectorize.io/sdks/python)
+
+## License
+
+Apache 2.0