Skip to main content

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)

Source distribution for cubesquare 1.2.0
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)

Table of built distributions (wheels) for cubesquare 1.2.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page