cubesquare 1.0.1

Instant Semantic Memory - 167M tokens/sec, 0.04ms queries, 100% deterministic

Cubesquare

Embeddings drift. Vectors collapse. Cubesquare doesn't.

New Users Start Here

# 1. Verify installation (8 checks)
python examples/first_run.py

# 2. Read the quickstart guide
# -> QUICKSTART.md

# 3. See RAG vs CST comparison
python examples/rag_vs_cst_comparison.py

# 4. Run all validation (119 checks total)
pytest tests/ -v                              # 68 tests
python agent_sandbox/agent_in_loop_validation.py  # 43 checks

Resource	Purpose
QUICKSTART.md	Beginner guide - start here
CHANGELOG.md	Recent updates
CLAUDE.md	Full technical reference for agents
examples/first_run.py	Verify your installation

---

A deterministic semantic memory engine where every piece of content hashes to a permanent 3D coordinate - same input, same position, forever. No model, no index rebuild, no equidistance collapse at scale.

from cubesquare import CSTMemory

memory = CSTMemory()
memory.write("/src/auth.py")              # 5.97 nanoseconds
results = memory.query("authentication")  # <0.04ms
print(results[0].basin)                   # 42 - semantic cluster

Why Not Just Use Embeddings?

CST isn't a faster vector database — it's a deterministic coordinate system that eliminates the need for training, cloud infrastructure, and probabilistic matching.

Problem at scale	Embeddings + Vector DB	Cubesquare CST
Identity at scale	Millions of vectors crowd together - distinct concepts become indistinguishable	Every input has a unique, permanent coordinate - identity preserved at any scale
Model dependency	Change the embedding model -> all vectors shift, queries break	No model. The hash IS the identity
Determinism	Same text -> different vectors across model versions	Same text -> same coordinate, every machine, every run, forever
Query cost	O(N) approximate nearest neighbor - 10-50ms+ at scale	O(1) direct computation - 0.04ms
Dependencies	Embedding model + vector DB + GPU/cloud	Zero (Python stdlib). Optional C backend for 83M ops/sec
Drift over time	Fine-tuning or retraining shifts the entire space	Coordinates are permanent by construction

The equidistance problem: As embedding databases grow to millions of entries, vectors cluster into indistinguishable regions. Two completely different concepts produce nearly-identical vectors, and no amount of reranking recovers the lost identity. CST doesn't have this problem - distinct content maps to distinct coordinates, always.

How It Works

Content                              Familiar analog
  -> Hash (FNV-1a)                   like SHA / content fingerprint
  -> 3D Coordinate (Morton code)     like Geohash, but 3D
  -> Basin (mod 131)                 like a consistent hash bucket
  -> Layer (L1-L9)                   like an index namespace

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

Concepts -> Things You Already Know

Cubesquare	What it does	Nearest analog	Why CST is different
Token	Content -> 32-bit hex ID	Content hash / fingerprint	Deterministic - same content, same ID forever
Morton code	Pack 3D coords into one integer	Geohash / S2 cell ID	Preserves 3D locality - nearby coords stay nearby
Basin (0-130)	Cluster tokens into 131 groups	Consistent hash ring	Fixed buckets - no rebalancing, no drift, no collapse
Layer (L1-L9)	Semantic type of a cluster	Index namespace / shard	Derived from basin - emergent, not assigned
I-Logic (5 states)	Predict routing before execution	Finite state machine	Algebraically closed - composable, no side effects
SRL (t = sqrt(d))	Collapse deep iterations	Skip list / HNSW shortcut	Exact formula, not heuristic - sqrt(d) replaces O(log N)

Installation

pip install .

Development mode:

pip install -e .

Zero required dependencies — runs entirely on Python stdlib.

Quick Start

from cubesquare import CSTMemory

memory = CSTMemory()

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

# Query by meaning - O(1) computation, not O(N) vector search
results = memory.query("authentication", limit=5)
for r in results:
    print(f"  {r.path} (basin={r.basin})")

# 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

9 Semantic Layers

Every token belongs to a layer based on its basin — like an automatic namespace that emerges from the content itself.

Layer	Name	Basins	Answers the question
L1	Geometric	0-14	What is its structure?
L2	Semantic	15-29	What does it mean?
L3	Spatial	30-43	Where is it?
L4	Functional	44-58	What does it do?
L5	Probabilistic	59-72	How certain is it?
L6	Emotional	73-87	What state is it in?
L7	Frequency	88-101	When does it occur?
L8	Electromagnetic	102-116	What forces act on it?
L9	Membrane	117-130	What are its boundaries?

Three additional agent-facing layers (L10-L12) handle self-identity, cross-agent communication, and unified field queries. See docs/LAYERS_MAP.md for full details.

I-Logic: Algebraic Routing

A 5-state algebra for predicting routing outcomes before execution - like a finite state machine where you can compose states and know the result without running the pipeline.

State	Value	Meaning
DIRECT	1	Pass through unchanged
INVERSE	-1	Reflect / negate
SPIRAL	+i	Rotate / expand
ANTI_SPIRAL	-i	Counter-rotate / focus
ABSORBED	0	Terminate (loop exit)

from cubesquare.i_logic import predict_route

# Predict routing outcome without execution
result = predict_route("gateway:DIRECT,firewall:INVERSE,sink:ABSORBED")
print(result['final_state'])  # ABSORBED - terminated at step 3

Performance

Tier	Level	Throughput	When to use
T0	Atomic (BMI2)	111B positions/sec	Per-thread instruction
T1	C Internal	83M ops/sec	Base throughput - use for planning
T2	Batch (1000)	57M ops/sec	Production - always batch
T3	Single call	0.3M ops/sec	AVOID - 190x slower than batching

# RIGHT: 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)

# WRONG: Python loop - 190x slower
# for coord in coords:
#     process(coord)

Query Latency Comparison

System	Type	Latency
Cubesquare CST	Semantic lookup	0.04ms
In-memory hash	Exact key only	~0.001ms
FAISS (GPU)	ANN search	1-10ms
Pinecone	Cloud vector DB	10-50ms
Elasticsearch	Full-text search	20-150ms

CST achieves sub-millisecond semantic queries through deterministic encoding. Hash lookups are faster but only support exact-key matching, not semantic search.

CLI

cubesquare --status                       # System status
cubesquare benchmark                      # Run benchmark
cubesquare i_logic status                 # I-Logic state
cubesquare i_logic multiply SPIRAL INVERSE
cubesquare primitives status              # O(1) primitive checks

35 command shells available. Run cubesquare --help for the full list.

Testing

# Run all tests
python tests/run_all.py

# Or with pytest
pytest tests/ -v

Verified: 68/68 tests pass. 400/400 Morton roundtrips. 131/131 basin coverage. 5/5 I-Logic algebra properties. 22 identity preservation tests.

Documentation

Document	Description
LAYERS_MAP.md	9 CST layers + 12-layer basin manifold
ROUTING_MAP.md	Visual MCP -> Shell -> Layer routing
MCP_TOOLS_MAP.md	Complete mapping of 33 MCP tools
VERIFIED_PRIMITIVES.md	O(1) primitive proofs
mcp_tools.json	Programmatic MCP tool definitions
layers.json	Programmatic layer definitions

License

MIT License - see LICENSE file.

---

Invented by Jesus Fernandez. Offline-first. Training-free. 100% Deterministic.