Oscillink — Self‑Optimizing Memory for Embedding Workflows. Bridge your own LLMs, Embedding Models, and databases.

A physics‑inspired, model‑free coherence layer that transforms candidate embeddings into an explainable working‑memory state via convex energy minimization. Deterministic receipts for audit. Conjugate‑gradient solve with SPD guarantees.

Build coherence into retrieval and generation. Deterministic receipts for every decision. Latency that scales gracefully with corpus size. This is the missing layer from your RAG stack.

Setup: synthetic “facts + traps” dataset — see the notebook for N, k, trials, seed. Reproducible via notebooks/04_hallucination_reduction.ipynb. Traps flagged; gate=0.01, off‑topic damp=0.5.

Latency scales smoothly: with fixed D, k, and CG tol, settle tends to remain stable with denser graphs. Reference E2E < 40 ms at N≈1200 on a laptop CPU.
Hallucination control: in our controlled study[1], Oscillink reduced trap selections while maintaining competitive F1. See the notebook for setup and reproduction.
Receipts: SHA‑256 state signature; optional HMAC‑SHA256. schema
Universal: works with any embeddings, no retraining. adapters · quickstart
Self‑optimizing: learns parameters over time. adaptive suite
Production: scales to millions. See scripts under scripts/ for reproducible benchmarks.

<a href="#quickstart">Get Started</a> · <a href="docs/reference/API.md">API Docs</a> · <a href="#proven-results">See Results</a> · <a href="notebooks/">Live Demos</a> <a href="https://github.com/Maverick0351a/Oscillink/actions/workflows/ci.yml">CI</a> · <a href="https://pypi.org/project/oscillink/">PyPI</a> · <a href="docs/reference/API.md">API</a> · <a href="docs/foundations/MATH_OVERVIEW.md">Math</a> · <a href="docs/reference/RECEIPTS.md">Receipts</a> · <a href="benchmarks/">Benchmarks</a> · <a href="notebooks/">Notebooks</a>

Overview
Quickstart
Adapters & Compatibility
Reproducibility
Performance
Method (Technical)
Deployment Options
Security, Privacy, Legal
Troubleshooting
Contributing & License
Changelog

pip install oscillink

Abstract. Oscillink is a physics‑inspired, model‑free coherence layer that transforms a set of candidate embeddings into an explainable working‑memory state by minimizing a strictly convex energy on a mutual‑kNN lattice. The system solves a symmetric positive‑definite (SPD) linear system via preconditioned conjugate gradients (CG), returning (i) refined embeddings U*, (ii) a deterministic, signed “receipt” with energy improvement ΔH, and (iii) per‑edge/null‑point diagnostics. No training is required; your embeddings are the model.

Install: pip install oscillink · Docs: API · Math: Overview · Receipts: Schema

Overview
Quickstart
Adapters & Compatibility
Reproducibility
Performance
Method (Technical)
Deployment Options
Security, Privacy, Legal
Troubleshooting
Contributing & License
Changelog

Overview

Oscillink builds a transient mutual‑kNN graph over N×D anchors Y and settles to a unique global optimum of a convex energy. The result is a coherent bundle of items for a query psi, along with an auditable “receipt” that explains the decision.

Outputs per run:

Refined state U* (coherent embeddings)
Receipt with ΔH (energy drop), term breakdown, CG iterations/residuals, and a SHA‑256 state signature (optional HMAC)
Diagnostics: null points (incoherent edges), chain/prior scores (optional)

The system is deterministic, explainable, and training‑free.

Quickstart

Minimal, 60 seconds:

pip install oscillink
python - <<'PY'
import numpy as np
from oscillink import Oscillink

# Anchors (N x D, float32) and a D-dim query
Y = np.random.randn(80,128).astype('float32')
psi = (Y[:10].mean(0) / (np.linalg.norm(Y[:10].mean(0))+1e-9)).astype('float32')

lat = Oscillink(Y, kneighbors=6, lamG=1.0, lamC=0.5, lamQ=4.0)
lat.set_query(psi)
lat.settle()

print("top-5:", [(b.get("id", i), round(b["score"],3)) for i,b in enumerate(lat.bundle(k=5))])
print("ΔH:", lat.receipt()["deltaH_total"])
PY

System requirements: Python 3.10–3.12, NumPy ≥ 1.22 (1.x/2.x supported). CPU only.

SDK at a glance:

from oscillink import Oscillink

# Y: (N, D) embeddings; psi: (D,) query (float32 recommended)
lattice = Oscillink(Y, kneighbors=6)
lattice.set_query(psi)
lattice.settle()
bundle  = lattice.bundle(k=5)   # coherent top-k
receipt = lattice.receipt()     # deterministic audit (energy breakdown)

Adapters & Compatibility

Embeddings: Bring your own (OpenAI, Cohere, Sentence‑Transformers, local). Shapes: Y: (N, D), psi: (D,), preferably near unit‑norm float32.
Dependencies: NumPy + small helpers; no framework lock‑in.
Adapters: see oscillink.adapters.* for simple text embedding utilities.
Tuning: Practical knobs are kneighbors, lamC, lamQ. CLI --tune and the adaptive suite offer data‑driven defaults.
Preprocessing: optional smart_correct can reduce incidental traps in noisy inputs.
Platforms: Windows, macOS, Linux.

Reproducibility

Claim → how to reproduce (scripts write JSON or plots):

| Claim | How to reproduce | |---|---| | Coherence vs cosine baseline on provided sample | python scripts/competitor_benchmark.py --input examples/real_benchmark_sample.jsonl --format jsonl --text-col text --id-col id --label-col label --trap-col trap --query-index 0 --k 5 --json --out benchmarks/competitor_sample.json then python scripts/plot_benchmarks.py --competitor benchmarks/competitor_sample.json --out-dir assets/benchmarks | | Scaling timing vs N | python scripts/scale_benchmark.py --N 400 800 1200 --D 64 --k 6 --trials 2 > benchmarks/scale.jsonl then python scripts/plot_benchmarks.py --scale benchmarks/scale.jsonl --out-dir assets/benchmarks | | Receipt proof (energy, signature) | pip install -e .[dev] then python scripts/proof_hallucination.py --seed 123 --n 1200 --d 128 |

Notes: The “facts + traps” setup used in the notebook is a controlled study to demonstrate controllability and auditability. Evaluate on your corpus before drawing production conclusions.

Performance

Reference (laptop, Python 3.11, NumPy BLAS, N≈1200, light receipts):

Graph build: ~18 ms
Settle: ~10 ms
Receipt: ~3 ms

Total: under ~40 ms.

As N grows (fixed D, k, tol), CG typically converges in 3–4 iterations with Jacobi preconditioning; end‑to‑end times scale smoothly.

Complexity: one matvec is O(Nk); overall solve ≈ O(D · cg_iters · N · k).

Method (Technical)

Oscillink minimizes a convex energy on a mutual‑kNN lattice:

$$ H(U)=\lambda_G|U-Y|F^2+\lambda_C,\mathrm{tr}(U^\top L{\mathrm{sym}}U)+\lambda_Q,\mathrm{tr}\big((U-\mathbf{1}\psi^\top)^\top,B,(U-\mathbf{1}\psi^\top)\big) $$

with optional path prior term $\lambda_P L_{\text{path}}$. Normal equations yield an SPD system $MU^*=F$ with

$$ M=\lambda_G I+\lambda_C L_{\mathrm{sym}}+\lambda_Q B+\lambda_P L_{\text{path}},\quad F=\lambda_G Y+\lambda_Q B,\mathbf{1}\psi^\top. $$

Properties. If $\lambda_G>0$ and $L_{\mathrm{sym}}, B, L_{\text{path}}$ are symmetric PSD, then $M$ is SPD ⇒ unique minimizer $U^*$. We solve with Jacobi‑preconditioned CG. Each run emits a receipt with $\Delta H$, per‑term energy, CG stats, and a SHA‑256 state signature (optional HMAC).

More detail: Foundations / Math Overview

Deployment Options

A. SDK (local)

Keep everything in‑process. See Install and examples under examples/.

B. Licensed container (customer‑managed)

Run the API entirely inside your VPC/cluster. No embeddings or content leave your network; only license/usage heartbeats if enabled.

<details> <summary>Container quickstart and operations (click to expand)</summary>

Quickstart (Docker)

Place a license at `deploy/licens

Oscillink

Install / Use

README