Metadata-Version: 2.4
Name: cubememory
Version: 0.1.2
Summary: Official Python SDK for Cube Memory — semantic search with 100% exact recall
Author-email: Cube Memory <dev@cubememory.com.br>
License-Expression: MIT
Project-URL: Homepage, https://cubememory.com.br
Project-URL: Documentation, https://cubememory.com.br/docs
Project-URL: Repository, https://github.com/cubememory/sdk-python
Keywords: vector-search,semantic-search,rag,llm-memory,mcp,cube-memory
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: async
Requires-Dist: httpx>=0.25; extra == "async"
Provides-Extra: all
Requires-Dist: httpx>=0.25; extra == "all"

# cubememory

Official Python SDK for **Cube Memory** — semantic search with **100% exact recall**, isolated multi-tenant islands, and native MCP support.

[![PyPI](https://img.shields.io/pypi/v/cubememory)](https://pypi.org/project/cubememory/)
[![npm](https://img.shields.io/npm/v/@cubememory/sdk)](https://www.npmjs.com/package/@cubememory/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

## Install

```bash
pip install cubememory          # sync (uses requests)
pip install cubememory[async]   # + async support (uses httpx)
```

## Quick Start

```python
from cubememory import CubeClient

cube = CubeClient(
    base_url="https://cubememory.com.br/gateway",
    api_key="cm_live_YOUR_KEY",
    project_id="proj_YOUR_PROJECT",
)

# Semantic search — 100% exact cosine recall (no ANN approximation)
results = cube.index("my-docs").search("wireless headphones", limit=10)
for r in results:
    print(f"[{r.score:.2f}] {r.text_preview}")

# Index a document
cube.index("my-docs").insert(
    id="doc-001",
    text="Noise cancelling Sony WH-1000XM5",
    metadata={"price": 349, "brand": "Sony"},
)

# LLM Memory (agent remembers between sessions)
cube.memory.store("User prefers dark mode and speaks Portuguese")
ctx = cube.memory.search("user preferences")

# PKM Notes
cube.notes.upsert(
    title="Meeting Q3",
    text="Discussed the roadmap and timeline.",
    tags=["meeting", "q3"],
)
notes = cube.notes.search("roadmap")
```

## Async Usage

```python
import asyncio
from cubememory.client import AsyncCubeClient

async def main():
    cube = AsyncCubeClient(
        base_url="https://cubememory.com.br/gateway",
        api_key="cm_live_YOUR_KEY",
        project_id="proj_YOUR_PROJECT",
    )
    results = await cube.index("my-docs").search("wireless headphones")
    memories = await cube.memory.search("user preferences")

asyncio.run(main())
```

## API Reference

### `CubeClient(base_url, api_key, project_id, timeout=30.0)`

| Param | Type | Description |
|---|---|---|
| `base_url` | `str` | Gateway URL, e.g. `https://cubememory.com.br/gateway` |
| `api_key` | `str` | Your API key (`cm_live_xxx`) |
| `project_id` | `str` | Your project ID (`proj_xxx`) |

---

### `cube.index(name)`

| Method | Description |
|---|---|
| `.insert(id, text, metadata?)` | Index a document |
| `.insert_many(docs[])` | Batch index |
| `.search(query, limit?, threshold?, filter?)` | Semantic search → `List[SearchResult]` |
| `.get(id)` | Fetch by ID |
| `.delete(id)` | Remove document |
| `.stats()` | Index statistics |

**`SearchResult`** fields: `id`, `score`, `text_preview`, `metadata`

---

### `cube.memory`

Agent memory — persists LLM context between sessions.

| Method | Description |
|---|---|
| `.store(text, layer?)` | Save memory (`"long-term"` or `"short-term"`) |
| `.search(query, limit?)` | Semantic search → `List[SearchResult]` |
| `.list(limit?)` | List all memories |
| `.delete(id)` | Delete a memory |

---

### `cube.notes`

PKM Notes — Obsidian-style knowledge base with AI auto-connections.

| Method | Description |
|---|---|
| `.upsert(title, text, id?, tags?)` | Create or update a note |
| `.list()` | List all notes → `List[Note]` |
| `.get(id)` | Full note with related notes → `NoteDetail` |
| `.search(query, limit?)` | Semantic search → `List[Note]` |
| `.delete(id)` | Delete note and its chunks |

---

## MCP Integration

Connect Claude, GPT, Cursor, or any MCP-compatible LLM:

```json
{
  "mcpServers": {
    "cube-memory": {
      "type": "http",
      "url": "https://cubememory.com.br/gateway/v1/mcp",
      "headers": {
        "Authorization": "Bearer cm_live_YOUR_KEY",
        "X-Project-Id": "proj_YOUR_PROJECT"
      }
    }
  }
}
```

Available MCP tools: `search_memory`, `store_memory`, `list_memories`, `search_notes`, `get_note`.

---

## LangChain / Agent Integration

```python
from cubememory import CubeClient

cube = CubeClient(base_url, api_key, project_id)

# Use as a LangChain retriever-style tool
def retrieve(query: str) -> list[str]:
    results = cube.index("knowledge-base").search(query, limit=5)
    return [r.text_preview for r in results]

# Agent memory tool
def remember(text: str) -> str:
    cube.memory.store(text)
    return f"Stored: {text[:60]}..."

def recall(query: str) -> str:
    results = cube.memory.search(query, limit=3)
    return "\n".join(r.text_preview for r in results)
```

---

## Why Cube Memory?

| | Cube Memory | Bancos vetoriais baseados em ANN/HNSW |
|---|:---:|:---:|
| **100% exact recall** | ✅ cosine float32 | ❌ ANN approximation |
| **Multi-tenant isolation** | ✅ island per project | ⚠️ shared index with filters |
| **MCP native** | ✅ built-in | ❌ |
| **Self-host footprint** | ✅ minimal, single-host friendly | ❌ heavy multi-service clusters |
| **LGPD/GDPR** | ✅ data never leaves your server | ❌ cloud by default |

---

## Links

- **Dashboard:** [cubememory.com.br](https://cubememory.com.br)
- **npm SDK:** [@cubememory/sdk](https://www.npmjs.com/package/@cubememory/sdk)
- **Issues:** [github.com/cubememory/sdk-python](https://github.com/cubememory/sdk-python)
