# Cubesquare

**Instant Semantic Memory** — 83M ops/sec, 0.04ms queries, 100% deterministic.

Embeddings drift. Vectors collapse. Cubesquare doesn't.

## Install

```bash
pip install cubesquare
```

Zero dependencies. Works on Python 3.10+.

## Quick Start

```python
from cubesquare import CSTMemory

memory = CSTMemory()

# Write content — returns a permanent coordinate
token = memory.write("/src/auth/login.py")
print(f"Basin: {token.basin}, Layer: L{token.layer}")

# Query by meaning — O(1) computation, not O(N) search
results = memory.query("authentication", limit=5)

# Navigate by layer
siblings = memory.L1.siblings(token)    # L1: Geometric — file hierarchy
similar  = memory.L2.similar(token)     # L2: Semantic — meaning clusters
nearby   = memory.L3.nearby(token)      # L3: Spatial — coordinate proximity
```

## Why Not Embeddings?

| Problem | Embeddings + Vector DB | Cubesquare |
|---------|------------------------|------------|
| **Identity at scale** | Vectors crowd together — distinct concepts become indistinguishable | Every input has a unique, permanent coordinate |
| **Model dependency** | Change embedding model → all vectors shift | No model. The hash IS the identity |
| **Determinism** | Same text → different vectors across versions | Same text → same coordinate, forever |
| **Query cost** | O(N) approximate search, 10-50ms+ | O(1) computation, 0.04ms |
| **Dependencies** | Embedding model + vector DB + GPU | Zero. Python stdlib only |

## How It Works

```
Content → Hash (FNV-1a) → 3D Coordinate (Morton) → Basin (mod 131) → Layer (L1-L9)
```

The coordinate IS the meaning. No lookup tables, no search, no approximation.

| Concept | What it does | Nearest analog |
|---------|--------------|----------------|
| **Token** | Content → 32-bit hex ID | Content hash |
| **Morton code** | 3D coords → single integer | Geohash (but 3D) |
| **Basin** (0-130) | Cluster into 131 groups | Consistent hash ring |
| **Layer** (L1-L9) | Semantic type | Index namespace |
| **I-Logic** | 5-state routing algebra | Finite state machine |
| **SRL** | t = √d iteration collapse | Skip list shortcut |

## 9 Layers

| Layer | Name | Basins | Question |
|-------|------|--------|----------|
| L1 | Geometric | 0-14 | What structure? |
| L2 | Semantic | 15-29 | What meaning? |
| L3 | Spatial | 30-43 | Where? |
| L4 | Functional | 44-58 | What operation? |
| L5 | Probabilistic | 59-72 | How certain? |
| L6 | Emotional | 73-87 | What state? |
| L7 | Frequency | 88-101 | What timing? |
| L8 | Electromagnetic | 102-116 | What force? |
| L9 | Membrane | 117-130 | What boundary? |

## I-Logic Algebra

5-state algebra for predicting routing outcomes before execution:

| State | Value | Meaning |
|-------|-------|---------|
| DIRECT | 1 | Pass through |
| INVERSE | -1 | Reflect |
| SPIRAL | +i | Expand |
| ANTI_SPIRAL | -i | Contract |
| ABSORBED | 0 | Terminate |

```python
from cubesquare.i_logic import multiply, ILogicState

result = multiply(ILogicState.SPIRAL, ILogicState.SPIRAL)
# Returns INVERSE (i × i = -1)
```

## Performance

| Tier | Throughput | Use case |
|------|------------|----------|
| T1 C Internal | 83M ops/sec | Base throughput |
| T2 Batch (1000) | 57M ops/sec | Production |
| T3 Single call | 0.3M ops/sec | Avoid — 190× slower |

```python
# Batch through C — 57M ops/sec
from cubesquare._core import morton_encode_batch_raw, create_coords_array
coords = create_coords_array([100,200,0, 101,201,0, 102,202,0])
results = morton_encode_batch_raw(coords, 3)
```

## CLI

```bash
cubesquare --status                        # System status
cubesquare ilogic multiply SPIRAL INVERSE  # I-Logic algebra
cubesquare primitives status               # O(1) primitive checks
cubesquare --list                          # All 51 shells
```

## MCP Server

58 tools for Claude Desktop and MCP-compatible clients:

```bash
cubesquare-mcp  # Start MCP server
```

Add to Claude Desktop config:
```json
{
  "mcpServers": {
    "cubesquare": {
      "command": "cubesquare-mcp"
    }
  }
}
```

## Verified

- 68/68 pytest tests passing
- 43/43 agent validation checks
- 400/400 Morton roundtrips
- 131/131 basin coverage
- 58 MCP tools
- 51 shells
- 31 native DLLs

---

## For Contributors

Clone the repo and install in development mode:

```bash
git clone https://github.com/Cubesquare-Token/CST.git
cd CST
pip install -e .
```

Run tests:

```bash
pytest tests/ -v                              # 68 tests
python agent_sandbox/agent_in_loop_validation.py  # 43 checks
```

### Project Structure

```
cubesquare/
├── _core/          # C backend bindings, Morton encoding
├── i_logic/        # 5-state algebra
├── layers/         # L1-L9 semantic layers
├── shells/         # 51 command shells
├── mcp/            # MCP server (58 tools)
├── visual/         # Web UI (WorkflowServer)
├── circular/       # Loop detection, SRL
├── primitives/     # O(1) verified operations
├── identity.py     # Identity coalescence, UIF coupling
├── unified.py      # Unified interface
├── data/beehive/   # Semantic index
└── native/hex_core/ # 31 DLLs
```

### Documentation

| Document | Description |
|----------|-------------|
| [CLAUDE.md](CLAUDE.md) | Full technical reference |
| [docs/LAYERS_MAP.md](docs/LAYERS_MAP.md) | 12-layer architecture |
| [docs/VALIDATED_DYNAMICS.md](docs/VALIDATED_DYNAMICS.md) | IEEE 754 validated dynamics |
| [docs/VERIFIED_PRIMITIVES.md](docs/VERIFIED_PRIMITIVES.md) | O(1) proofs |

---

**Cubesquare Research License v1.0** — See [LICENSE](LICENSE) for details.

*Offline-first. Training-free. Deterministic.*
