From 1fa8d9150c67724da72bee4a026f89131b8c8b2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Tue, 16 Dec 2025 14:28:45 +0100 Subject: [PATCH] ci: check compatibility with python 3.11, 3.12 and 3.13 (#35) --- .github/workflows/test.yml | 23 +++ hindsight-api/README.md | 138 +++++++++++++++++- hindsight-api/pyproject.toml | 4 +- .../docs/sdks/integrations/local-mcp.md | 6 +- hindsight/README.md | 2 +- hindsight/pyproject.toml | 2 +- 6 files changed, 167 insertions(+), 8 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d97a635c..4fe99f37 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -38,6 +38,29 @@ jobs: working-directory: ./${{ matrix.path }} run: uv build + build-api-python-versions: + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.11', '3.12', '3.13'] + + steps: + - uses: actions/checkout@v4 + + - name: Install uv + uses: astral-sh/setup-uv@v5 + with: + enable-cache: true + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + + - name: Build hindsight-api + working-directory: ./hindsight-api + run: uv build + build-typescript-client: runs-on: ubuntu-latest diff --git a/hindsight-api/README.md b/hindsight-api/README.md index 2fd67659..8b35462e 100644 --- a/hindsight-api/README.md +++ b/hindsight-api/README.md @@ -1 +1,137 @@ -# Memory \ No newline at end of file +# 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 diff --git a/hindsight-api/pyproject.toml b/hindsight-api/pyproject.toml index e43b675f..6efbdd1a 100644 --- a/hindsight-api/pyproject.toml +++ b/hindsight-api/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "hindsight-api" version = "0.1.6" -description = "Temporal + Semantic + Entity Memory System for AI agents using PostgreSQL" +description = "Hindsight: Agent Memory That Works Like Human Memory" readme = "README.md" requires-python = ">=3.11" dependencies = [ @@ -25,7 +25,7 @@ dependencies = [ "greenlet>=3.2.4", "psycopg2-binary>=2.9.11", "transformers>=4.30.0,<4.46.0", - "torch>=2.0.0,<2.6.0", + "torch>=2.0.0", "tiktoken>=0.12.0", "httpx>=0.27.0", "fastmcp>=2.3.0", diff --git a/hindsight-docs/docs/sdks/integrations/local-mcp.md b/hindsight-docs/docs/sdks/integrations/local-mcp.md index e710bbb2..bc9b8f62 100644 --- a/hindsight-docs/docs/sdks/integrations/local-mcp.md +++ b/hindsight-docs/docs/sdks/integrations/local-mcp.md @@ -16,7 +16,7 @@ This is ideal for: ### With uvx (recommended) ```bash -uvx hindsight-api@latest hindsight-local-mcp +uvx --from hindsight-api hindsight-local-mcp ``` ### With pip @@ -35,7 +35,7 @@ Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json`): "mcpServers": { "hindsight": { "command": "uvx", - "args": ["hindsight-api@latest", "hindsight-local-mcp"], + "args": ["--from", "hindsight-api", "hindsight-local-mcp"], "env": { "HINDSIGHT_API_LLM_API_KEY": "your-openai-key" } @@ -53,7 +53,7 @@ By default, memories are stored in a bank called `mcp`. To use a different bank: "mcpServers": { "hindsight": { "command": "uvx", - "args": ["hindsight-api@latest", "hindsight-local-mcp"], + "args": ["--from", "hindsight-api", "hindsight-local-mcp"], "env": { "HINDSIGHT_API_LLM_API_KEY": "your-openai-key", "HINDSIGHT_API_MCP_LOCAL_BANK_ID": "my-personal-memory" diff --git a/hindsight/README.md b/hindsight/README.md index f7f36422..6668dace 100644 --- a/hindsight/README.md +++ b/hindsight/README.md @@ -1,6 +1,6 @@ # hindsight-all -All-in-one package for Hindsight - Semantic memory system with personality-driven thinking for AI agents. +All-in-one package for Hindsight - Agent Memory That Works Like Human Memory ## Quick Start diff --git a/hindsight/pyproject.toml b/hindsight/pyproject.toml index d7430bb4..67ecc3b2 100644 --- a/hindsight/pyproject.toml +++ b/hindsight/pyproject.toml @@ -5,7 +5,7 @@ build-backend = "hatchling.build" [project] name = "hindsight-all" version = "0.1.6" -description = "All-in-one package for Hindsight - Semantic memory system with personality-driven thinking" +description = "Hindsight: Agent Memory That Works Like Human Memory - All-in-One Bundle" readme = "README.md" requires-python = ">=3.11" dependencies = [