Metadata-Version: 2.4
Name: hippocortex
Version: 1.2.0
Summary: Official Hippocortex Python SDK — AI agent memory that learns from experience
Author-email: Hippocortex <dev@hippocortex.dev>
License-Expression: MIT
Project-URL: Homepage, https://hippocortex.dev
Project-URL: Documentation, https://docs.hippocortex.dev
Project-URL: Repository, https://github.com/hippocortex/hippocortex-os
Project-URL: Bug Tracker, https://github.com/hippocortex/hippocortex-os/issues
Project-URL: Changelog, https://github.com/hippocortex/hippocortex-os/blob/main/CHANGELOG.md
Keywords: hippocortex,ai,memory,agents,llm,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.1.0; extra == "openai-agents"
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
Provides-Extra: crewai
Requires-Dist: crewai>=0.50.0; extra == "crewai"
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2.0; extra == "autogen"
Provides-Extra: all
Requires-Dist: openai-agents>=0.1.0; extra == "all"
Requires-Dist: langgraph>=0.2.0; extra == "all"
Requires-Dist: crewai>=0.50.0; extra == "all"
Requires-Dist: pyautogen>=0.2.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# hippocortex

Official Python SDK for [Hippocortex](https://hippocortex.dev), AI agent memory that learns from experience.

## Install

```bash
pip install hippocortex

# With adapter support:
pip install hippocortex[openai-agents]  # OpenAI Agents SDK
pip install hippocortex[langgraph]      # LangGraph
pip install hippocortex[crewai]         # CrewAI
pip install hippocortex[autogen]        # AutoGen
pip install hippocortex[all]            # All adapters
```

## Quick Start

Choose the integration method that fits your workflow:

### Auto-Instrumentation (Easiest, 1 Line)

```python
import hippocortex.auto
from openai import OpenAI

client = OpenAI()

# Every call now has persistent memory automatically:
# - Past context is synthesized and injected
# - The conversation is captured for future learning
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Deploy payments to staging"}]
)
```

### wrap() (Recommended)

```python
from hippocortex import wrap
from openai import OpenAI

# Wrap your client. Explicit, per-client control.
client = wrap(OpenAI())

# Use exactly as before. Memory is transparent.
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Deploy payments to staging"}]
)

# Works with Anthropic too:
from anthropic import Anthropic
client = wrap(Anthropic())
```

### Manual Client (Advanced)

```python
import asyncio
from hippocortex import Hippocortex
from hippocortex.types import CaptureEvent

async def main():
    hx = Hippocortex(api_key="hx_live_...")

    # 1. Capture agent events
    await hx.capture(CaptureEvent(
        type="message",
        session_id="sess-1",
        payload={"role": "user", "content": "Deploy payment service to staging"}
    ))

    # 2. Learn from experience
    await hx.learn()

    # 3. Synthesize context for decisions
    ctx = await hx.synthesize("deploy payment service")
    for entry in ctx.entries:
        print(f"[{entry.section}] {entry.content}")

asyncio.run(main())
```

### Synchronous Client

```python
from hippocortex import SyncHippocortex
from hippocortex.types import CaptureEvent

hx = SyncHippocortex(api_key="hx_live_...")

result = hx.capture(CaptureEvent(
    type="message",
    session_id="sess-1",
    payload={"role": "user", "content": "Hello"}
))
print(result.event_id)
```

## Zero-Config

Both `auto` and `wrap()` resolve configuration automatically:

1. Explicit arguments passed to `wrap()` or `Hippocortex()`
2. Environment variables: `HIPPOCORTEX_API_KEY`, `HIPPOCORTEX_BASE_URL`
3. `.hippocortex.json` file (searched from cwd upward)

### .hippocortex.json

```json
{
  "apiKey": "hx_live_your_key_here",
  "baseUrl": "https://api.hippocortex.dev/v1"
}
```

## Auto-Memory Adapters

Wrap your agents with **one line** to get automatic memory capture and context injection.

### OpenAI Agents SDK

```python
from agents import Agent, Runner
from hippocortex import auto_memory

agent = Agent(name="assistant", instructions="You are helpful.")
agent = auto_memory(agent, api_key="hx_live_...")

# Or with env var HIPPOCORTEX_API_KEY:
agent = auto_memory(agent)

result = await Runner.run(agent, "Deploy to staging")
```

The adapter automatically:
- Synthesizes past context before each run (injected into instructions)
- Captures user messages, assistant responses, and tool calls
- Gracefully degrades if the server is unreachable

### LangGraph

```python
from hippocortex.adapters import langgraph as hx_langgraph

# Wrap a compiled LangGraph
graph = builder.compile()
graph = hx_langgraph.wrap(graph, api_key="hx_live_...")

# Use normally — memory is automatic
result = await graph.ainvoke({"messages": [{"role": "user", "content": "deploy"}]})
```

Supports `ainvoke`, `invoke`, and `astream`.

### CrewAI (Beta)

```python
from hippocortex.adapters import crewai as hx_crewai

crew = hx_crewai.wrap(crew, api_key="hx_live_...")
result = crew.kickoff()
```

Injects memory context into agent backstories and captures task results.

### AutoGen (Beta)

```python
from hippocortex.adapters import autogen as hx_autogen

agent = hx_autogen.wrap(agent, api_key="hx_live_...")
agent.initiate_chat(other_agent, message="Hello")
```

Captures messages and injects synthesized context via reply hooks.

### OpenClaw

```python
from hippocortex.adapters import openclaw as hx_openclaw

middleware = hx_openclaw.create_middleware(api_key="hx_live_...")

# On incoming message:
context = await middleware.on_message("Deploy the service")
# context = "# Hippocortex Memory Context\n..."

# After generating response:
await middleware.on_response("Deployment complete!")
```

## Configuration

All adapters support:

| Option | Env Var | Default | Description |
|--------|---------|---------|-------------|
| `api_key` | `HIPPOCORTEX_API_KEY` | (required) | API key |
| `base_url` | `HIPPOCORTEX_BASE_URL` | `https://api.hippocortex.dev/v1` | API URL |
| `session_id` | — | auto-generated | Session ID |

## Key Behaviors

- **Fire-and-forget capture**: Capture calls never block the agent
- **Error swallowing**: All Hippocortex errors are logged and swallowed — your agent never crashes because of memory
- **Graceful degradation**: If the server is unreachable, adapters return empty context and continue
- **Session tracking**: Auto-generated session IDs link related events

## API Reference

### `Hippocortex(api_key, base_url?, timeout?)`

Async client. Use with `await`.

- `capture(event)` → `CaptureResult`
- `capture_batch(events)` → `BatchCaptureResult`
- `learn(options?)` → `LearnResult`
- `synthesize(query, options?)` → `SynthesizeResult`
- `list_artifacts(...)` → `ArtifactListResult`
- `get_artifact(id)` → `Artifact`
- `get_metrics(...)` → `MetricsResult`

### `SyncHippocortex(api_key, base_url?, timeout?)`

Synchronous client. Same methods, no `await` needed.

## License

MIT
