SynapticLite

A projection firewall for larger local LLMs.

SynapticLite keeps durable context in inspectable JSON files, asks a small local model (or deterministic code) to assemble a compact cited briefing, checks that briefing in code, and only then opens a single-use gate to a larger local model.

It is a clean, runner-neutral extraction of the projection-clerk architecture accepted in Synaptic Build 009.

durable JSON sources
        │
        ▼
small clerk or deterministic assembler
        │
        ▼
projection draft ──► deterministic review ──► hash-bound, single-use gate
                                                   │
                                      unload clerk │ load boss
                                                   ▼
                                          large local model
                                                   │
                                                   ▼
                                              run receipt

Why

Large local models compete with their own KV cache, the runner, and the rest of the machine for unified memory. Sending a whole knowledge base on every turn is usually the wrong default. SynapticLite instead treats the context window as a scarce execution surface:

• JSON sidecars are the durable memory.
• A projection is a temporary, cited briefing assembled for one request.
• A separate deterministic reviewer checks sources, hashes, freshness, trust labels, and token budgets.
• The large model receives only the approved projection.
• A gate is bound to the exact projection, runner, and model, then consumed once.

This does not make context token-free and it does not make model weights smaller. The boss still receives the approved projection in its prompt. The benefit is bounded prompt/KV-cache use, auditable context selection, and the ability to unload a clerk before loading a solo or heavy model.

Runner support

The base adapter uses /v1/chat/completions, which makes the same code usable with:

Runner	Default local URL	Support
Ollama	http://127.0.0.1:11434/v1	OpenAI-compatible; optional native keep-alive control
LM Studio	http://127.0.0.1:1234/v1	OpenAI-compatible; optional native load/unload control
llama.cpp server	http://127.0.0.1:8080/v1	OpenAI-compatible
MLX-LM server	http://127.0.0.1:8080/v1	OpenAI-like chat server
Other local runners	configurable	Any compatible chat-completions endpoint

Runner names are profiles, not an enum. A new runner can implement the small Runner protocol or use CallbackRunner in-process.

Status

0.1.0a2 is an alpha:

• The deterministic assembler, reviewer, repair path, gate, and JSON store are the reference security boundary.
• Model-backed clerks are experimental workers. Their output is untrusted until deterministic citation and budget checks pass.
• The default trust model is a single local operator. Records are tamper-evident, not tamper-proof against an attacker who controls the workspace.
• No model weights are bundled or downloaded.

See Architecture, Security, runner compatibility, and the Build 009 extraction record before production use. The live 64 GB Mac validation records the first real clerk-to-boss run, and the roadmap tracks the path beyond the first alpha.

Easiest start

SynapticLite now includes a guided setup and a private local desktop. The setup discovers models exposed by your local runner, lets you choose an optional clerk and an exact boss model, and creates a safe starter workspace without requiring you to hand-edit configuration JSON.

On a Mac, clone or download this repository and double-click launch.command. It creates an isolated .venv, starts guided setup the first time, and then opens the desktop. On macOS or Linux you can do the same from a terminal:

./install.sh

On Windows, open PowerShell in the repository and run:

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

That execution-policy override applies only to this one PowerShell process.

After setup, open the control panel at any time with:

./.venv/bin/synapticlite desktop

The desktop listens on loopback only. It can create and edit JSON memory, check configured models, prepare a projection for inspection, and run the approved projection through the boss. No cloud service, telemetry, or bundled model is involved. See the easy-start guide for the full Mac, Linux, and Windows walkthrough.

Install from source

git clone https://github.com/cryptosourusTex/SynapticLite.git
cd SynapticLite
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

SynapticLite has no required third-party runtime dependencies.

Quick start

Initialize a workspace and a directory for durable JSON sources:

synapticlite init --workspace .synapticlite --sources ./state

The generated .synapticlite/config.json contains separate clerk and boss runner profiles. Point either profile at Ollama, LM Studio, llama.cpp, MLX-LM, or another compatible local endpoint, then add JSON files under ./state.

Check the configured endpoints without running a generation:

synapticlite doctor --workspace .synapticlite

Prepare and review a projection without firing the boss:

synapticlite prepare \
  --workspace .synapticlite \
  --instruction "Compare the current architecture options and recommend one"

Run the full lifecycle (clerk → review → gate → boss):

synapticlite run \
  --workspace .synapticlite \
  --instruction "Compare the current architecture options and recommend one"

Every draft, review, repair, gate, and run receipt is JSON under the workspace. Use synapticlite inspect --workspace .synapticlite RECORD_ID to inspect one.

For copyable Ollama and LM Studio configurations, see the examples guide.

Core API

from synapticlite import (
    JsonArtifactStore,
    JsonDirectorySource,
    ModelTarget,
    ProjectionPolicy,
    ProjectionRequest,
    SynapticLite,
)
from synapticlite.runners import OpenAICompatibleRunner

sources = JsonDirectorySource("state")
store = JsonArtifactStore(".synapticlite")
policy = ProjectionPolicy(
    default_context_tokens=8_192,
    max_safe_context_tokens=24_576,
    output_reserve_tokens=2_048,
)
lite = SynapticLite(store=store, sources=sources, policy=policy)

boss = OpenAICompatibleRunner(
    profile="ollama",
    base_url="http://127.0.0.1:11434/v1",
    runner_id="ollama",
    model="qwen3:14b",
)

request = ProjectionRequest(
    request_id="architecture-review-001",
    instruction="Compare the architecture options and recommend one.",
    target=ModelTarget(
        runner_id=boss.capabilities.runner_id,
        model_id="qwen3:14b",
    ),
)

prepared = lite.prepare(request)
if prepared.gate is not None:
    receipt = lite.execute_gate(prepared.gate.gate_id, runner=boss)
    print(receipt.output_text)

The exact API is intentionally small. Host applications own the meaning of their state; SynapticLite owns selection, projection integrity, and the firing gate.

Design rules

1. Durable state, not a context window, is memory.
2. Large models are bosses, not clerks.
3. The checker is not the worker.
4. Model output is a proposal; deterministic code is the gate.
5. Default context is a budget. Maximum context is a ceiling, not a target.
6. A gate is exact, expiring, and single-use.
7. Local-first means loopback-first and no secret values in stored config.

When a model-backed clerk is enabled, the CLI unloads an Ollama clerk after its projection call (keep_alive=0) or asks LM Studio to release the clerk before the boss residency step. Custom runner integrations own their equivalent handoff and should implement it before using solo-lane models.

Contributing

Runner adapters, token estimators, source connectors, and adversarial test fixtures are welcome. Read CONTRIBUTING.md first.

License

Apache-2.0. Model and runner licenses remain independent of SynapticLite.