cabinet-hsh 0.1.4

Python bindings for Cabinet - Hierarchical Semantic Hashing memory retrieval

cabinet

Python bindings for Cabinet — a discrete semantic memory retrieval system for AI agents.

Replace 768-dim dense vectors with 20-bit structured integer codes and retrieve on pure CPU with O(log n) B-tree prefix matching.

---

What is Cabinet?

Cabinet is a memory retrieval engine designed for Agent scenarios where you need to:

• Remember large amounts of text on a laptop or edge device
• Recall relevant snippets fast, without GPU
• Explain why a snippet was retrieved (category → cluster → word, four-level matching)
• Update incrementally without rebuilding the whole index

The core idea is Hierarchical Semantic Hashing (HSH): each word is encoded as a 20-bit structured integer:

┌──────┬─────────┬─────────┐
│ feat │   sim   │   abs   │
│ 4-bit│  8-bit  │  8-bit  │
└──────┴─────────┴─────────┘
   ↓        ↓         ↓
 POS tag  cluster   bucket

Retrieval becomes integer prefix matching on B-trees, which is tiny, fast, and fully auditable.

---

Installation

# Core package (pre-compiled wheels, no Rust needed)
pip install cabinet-hsh

# With optional GUI visualization
pip install cabinet-hsh[gui]

# With document parsing (PDF, DOCX, XLSX)
pip install cabinet-hsh[docs]

# With plotting utilities
pip install cabinet-hsh[plot]

# Development install from source (requires Rust 1.72+)
git clone https://github.com/Sauomore/Cabinet.git
cd Cabinet/cabinet
maturin develop

---

Quick Start

import cabinet

# Open a memory cabinet (~4MB RAM + single SQLite file)
mem = cabinet.Memory(
    path="./agent_memory.db",
    precision="light",    # light | hybrid | precise
    pos_threshold=50,     # common-word promotion threshold
    max_context=4096,     # working-memory window
)

# Insert snippets
mem.insert("用户明天下午3点开会，准备PPT。")
mem.insert("用户喜欢听管弦乐。")
mem.insert("5号楼邻居有梯子，平时放在车库。")

# Query
results = mem.query("会议准备", top_k=5)
for r in results:
    level = ["关联", "同类", "同簇", "精确"][r.match_level - 1]
    print(f"[{level}] score={r.score:.3f} doc_id={r.doc_id}")
    if r.match_level >= 3:
        print(f"  → {mem.decode(r)}")

# Snapshot and close
mem.snapshot("./backup/agent_memory_2026-07-03.db")
mem.close()

---

API Overview

cabinet.Memory

Memory(
    path: str,               # SQLite database path
    precision: str,          # "light" | "hybrid" | "precise"
    pos_threshold: int,      # frequent-word promotion threshold
    max_context: int,        # working-memory capacity in tokens
)

Methods:

• insert(text: str) -> int — tokenize, encode, and store a document; returns doc_id
• query(text: str, top_k: int = 10) -> list[QueryResult] — retrieve top-k matches
• decode(result: QueryResult) -> str | None — decode the original text of a result
• snapshot(dst: str) -> None — copy the database to dst
• close() -> None — close the database

cabinet.QueryResult

A result object with the following fields:

Field	Type	Meaning
doc_id	int	document ID
position	int	word position inside the document
score	float	relevance score
match_level	int	1=related, 2=same category, 3=same cluster, 4=exact

Context decoding

from cabinet import decode_context

results = mem.query("借梯子", top_k=3)
for r in results:
    text = decode_context(mem, r, mode="sentence")
    print(text)

Supported mode values: "paragraph", "sentence", "window", "before", "after", "window_sent".

---

Supported Platforms

Pre-compiled wheels are provided for:

• Linux: x86_64, aarch64 (manylinux)
• macOS: universal2 (Intel + Apple Silicon)
• Windows: x64, x86

Requires Python ≥ 3.8 (CPython).

---

Architecture

cabinet (Python API)
  └── PyO3 bindings
      └── cabinet-core (Rust)
          ├── cabinet-hsh     # 20-bit HSH encoding
          ├── cabinet-index   # B-tree prefix index + LSM
          ├── cabinet-store   # SQLite backend
          └── cabinet-router  # relevance routing

Three-layer memory model:

1. Token Store — raw HSH sequences, append-only WAL buffer
2. Archive Index — 16 feature drawers with B-tree (sim, abs) indexes
3. Working Memory — LRU hot cache for inference-time hits

---

When to use Cabinet vs. vector databases

Scenario	Cabinet	FAISS / Chroma
Laptop / edge device	✅ Tiny CPU model	❌ Needs GPU or large RAM
Incremental updates	✅ Append-only	❌ Rebuild clusters
Explainable retrieval	✅ Auditable path	❌ Black-box similarity
Semantic similarity	⚠️ Discrete approximation	✅ Dense vectors

Use Cabinet when you need a small, fast, explainable, and incrementally-updatable memory for Agents.

---

GUI Visualization

If you installed with [gui]:

cabinet-gui
# or
cd cabinet-gui
streamlit run app.py

The GUI includes pages for encoding visualization, memory architecture, retrieval paths, index browser, and an interactive console.

---

License

MIT OR Apache-2.0

---

Cabinet — let AI remember, and explain why it remembers.