Semantix

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.

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.

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.

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.

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.

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.

• 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.

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 .semantix/project.db   # L2 reuse block
semantix verify  --session <session-dir> --project demo                    # replay gate (≥70%)
semantix dashboard                                                         # one-screen snapshot

Prefer to build from source (Go 1.26+)? go build -o semantix ./cmd/semantix && go build -o semantix-agent ./cmd/semantix-agent. Full command reference and configuration: docs/QUICKSTART.md.

Cursor, Windsurf, Codex CLI, Gemini CLI, Copilot agent mode and Cline / Continue / Aider all reach the kernel through one of the paths above; none requires kernel changes. Priorities follow observed usage — concrete integration requests are tracked as issues (template: .github/ISSUE_TEMPLATE/integration_request.yml).

• 💬 GitHub Discussions — Q&A, ideas, show & tell
• 🐛 Issue tracker — good first issue is the place to start
• 📖 Blog — semantic caching and agent-memory write-ups

Semantix is early-stage. Contributions are welcome across semantic caching, retrieval, scheduling, speculative execution, evaluation methodology and harness adapters — see CONTRIBUTING.md for the workflow (branch from main, PRs require green go vet and go test -race). Issues and PRs in English or Chinese are both fine.

Without writing code: run semantix verify against your own sessions and post the resulting hit rate to #58. Aggregated community results decide the v1.0 gate.

Architectural assumptions are open to challenge; testing them is part of the work.

MIT. DeepSeek-Reasonix (MIT).