semantix-guide

Semantix

Cross-session memory for AI coding agents — and a much smaller bill.

Semantic Caching · Adaptive Scheduling · Speculative Prefetch · Cross-Session Learning

English · 简体中文 · Quickstart · Technical Overview · Website

A coding agent loses its entire context when a session ends, and a provider's prefix cache hits only on byte-identical prompts — a single edit near the head invalidates everything after it.

Semantix addresses both: a complete coding agent with the memory kernel built in, and a standalone kernel that attaches to an agent already in use.

Quick start

Install — one line, macOS / Linux (arm64 / amd64):

curl -fsSL https://raw.githubusercontent.com/Gnosil/semantix/main/agent-skill/scripts/install.sh | sh

This drops semantix + semantix-agent into ~/.local/bin and turns on cross-session memory. Use it — start the agent inside any project; that folder becomes the workspace:

cd ~/your-project
semantix                 # bare command → launch the coding agent here (first run sets up provider / API key)
semantix search "..."    # any subcommand → the memory kernel (search / extract / inject / verify / usage)

Pin a version or arch with ... | sh -s -- v0.7.2 arm64. Other install methods and the full command reference live in docs/QUICKSTART.md.

Two ways to run it

semantix-agent — the complete agent. A CLI coding agent shipping with the memory kernel built in: extraction, retrieval, injection and the evolution loop are wired at boot, with provider presets for ~50 endpoints.

The kernel — attached to an existing agent. Harness-independent by design; the integration surface is a small set of hooks (tool registration, message interception, session export / event bypass). Three ways in:

Fail-open throughout: on kernel error the agent falls back to its normal execution path.

Cross-session memory

A project's build conventions, test layout and service flags have to be re-established in every new session. Semantix extracts reusable slices from finished sessions — task patterns, project knowledge, tool sequences, verified results — into a local scored library, and reinjects the relevant ones when a similar task appears. Each hit carries its retrieval zone (🟢 hit · 🟡 grey · ⚪ miss) and its source session — real semantix search / dashboard / verify output lives in the reuse visualization walkthrough.

Hits, misses and manual corrections all feed back into slice scores and retrieval thresholds, so precision improves with use rather than volume alone. Type-aware eviction discards stale results first and retains project knowledge.

Cache hit rate and cost

Provider prefix caches match byte-exactly: a hit requires the prompt to be identical to the previous one byte for byte, and a single differing character near the head invalidates everything after it.

The impact of that failure mode is routinely underestimated. Claude Code writes a per-request billing marker into the head of the system prompt. First-party endpoints strip it server-side; third-party endpoints do not, so there the line invalidates the cache from the first token. The spec behind the prefix-hygiene middleware attributes a 133× difference in hit rate to that single header, and records cache spend rising 4–5× when stripping is disabled. semantix-gateway strips it by default.

The design goal is to make the provider cache hittable rather than to work around it:

• Byte-stable injection — retrieved slices are ordered by ID rather than by score, so semantically similar requests produce byte-identical prefixes.
• Prefix hygiene — per-request attribution markers are stripped and the tool array is canonicalized by name, removing client enumeration order as a source of invalidation.
• Provider awareness — a vendor capability table, per-vendor cache lifetimes (DeepSeek's 24-hour on-disk context cache, Anthropic's 5-minute ephemeral window), budget-aware cache_control breakpoint placement, and per-model price tables.
• L3 result reuse — a verified result is returned without a model call, fail-closed.

Per-provider adaptation

Cache behaviour is determined by the stack serving the model rather than by the model itself, and the spread is wide enough to require per-stack adaptation.

Both are per-turn prompt-token hit rates — hit / (hit + miss) over cache token counts returned by the provider, not estimates. semantix-agent displays the current turn's rate alongside the session average in its status line, so the figure is verifiable on any workload.

A week-long GLM study measured the same model behind different hosts and found cache lifetimes differing several-fold: one stack held a prefix for 1–8 minutes with real expiry in (8, 12]; another maintained 96–98% for 120 seconds and had fallen to 28% at 301 seconds. This is why the TTL table is per-vendor rather than a single global value, and why GLM hit-rate telemetry carries a documented ~97.6% reporting ceiling — trailing partial blocks never count as cached.

Method and raw runs: docs/reports/glm-spike-week.md · docs/reports/glm-p0-1-prefix-audit.md.

Beyond caching, the scheduler learns tool-usage patterns to parallelize eligible calls and to prefetch read-only context during model wait time.

Measured

• 79.8% cost saved on a synthetic replay comparison — methodology in docs/reports/m0-cost-comparison.md
• 80% cache hit rate (L3/L2) on a small demo library (4 extracted sessions) — the one-screen semantix dashboard snapshot is captured in the reuse visualization walkthrough
• A replay gate (semantix verify) enforces ≥ 70% relevance; validating that hit rate on real user sessions is the open v1.0 gate — #58

These are replay / demo measurements, not production benchmarks. The full evidence trail — and everything else technical — lives in docs/TECHNICAL-OVERVIEW.md.

Try it in 30 seconds

Installed via the one-liner above? Extract slices from a past session, then reuse them — this is the memory kernel at work:

semantix extract --input session.jsonl --db .semantix/project.db --project demo
semantix search  --query "fix failing go test" --db .semantix/project.db
semantix inject  --query "fix failing go test" --db .