Cubesquare
Instant Semantic Memory — 83M ops/sec, 0.04ms queries, 100% deterministic.
Embeddings drift. Vectors collapse. Cubesquare doesn't.
Install
pip install cubesquare
Zero dependencies. Works on Python 3.10+.
Quick Start
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 |
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 |
# 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
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:
cubesquare-mcp # Start MCP server
Add to Claude Desktop config:
{
"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:
git clone https://github.com/Cubesquare-Token/CST.git
cd CST
pip install -e .
Run tests:
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 | Full technical reference |
| docs/LAYERS_MAP.md | 12-layer architecture |
| docs/VALIDATED_DYNAMICS.md | IEEE 754 validated dynamics |
| docs/VERIFIED_PRIMITIVES.md | O(1) proofs |
Cubesquare Research License v1.0 — See LICENSE for details.
Offline-first. Training-free. Deterministic.
Metadata
Release files for cubesquare 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cubesquare-1.2.0.tar.gz | 1.4 MB | Without provenance | Details for cubesquare-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cubesquare-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for cubesquare-1.2.0-py3-none-any.whl |
Total release size: 2.9 MB
Release files / cubesquare-1.2.0.tar.gz
| Download URL | cubesquare-1.2.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
426b3cdd98f9a86a00939b65b0ba1276ca9b512e3c828f75871080fb067a14de
|
|
BLAKE2b-256 checksum How to use checksums |
8c35e3c49618fa35e3260fcaad0dbcaf3a271bb3eb8763727e0b7d0b51cf620a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.3
|
Release files / cubesquare-1.2.0-py3-none-any.whl
| Download URL | cubesquare-1.2.0-py3-none-any.whl |
|---|---|
| Size | 1.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
980e5d26715ec3feb9de667b06c87a6ae46995662f41e9ddb7e75e202e3d6cda
|
|
BLAKE2b-256 checksum How to use checksums |
575dae6b277ec5a6e4f18639455dd9f4b6c6293c10b1ee2d7c3e5da3cc5c51ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.3
|
Security for cubesquare 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.