local-first alpha admission decision contract / v1 WriteFence memory gateway

Gate agent memory before it persists.

Every write gets an admission decision: allowed, warned, quarantined, or blocked, with traceable reasons and replay before bad context becomes durable state.

four-state ADC / allow, warn, quarantine, or block before persistence

replayable evidence / every decision has rule, reason, retry, review, trace

operator surface / WAL replay, quarantine review, local UI, CLI

View on GitHub Run locally Check compatibility

fig.01 / write admission path

source

Agent / MCP client

POST /documents/text
payload: text, source, trace

admission

WriteFence :9622

built-in rules, optional semantic checks, WAL, ADC

upstream

Memory store

receives only allowed or warned writes

allowed warned quarantined blocked

forwarded

allowed writes reached the upstream store

held local

review-required writes stayed out of memory

rejected

policy-breaking writes returned structured ADC

developer note

write once,
inspect first

trace IDs beat memory archaeology

prefix_required[STATUS], [DECISION], [RUNBOOK]

context_shieldsensitive context is rejected before persistence

semantic_dedupoptional review with embeddings plus Qdrant

trace captured before memory policy diff stays replayable review queue before persistence bad context never becomes archaeology trace captured before memory policy diff stays replayable review queue before persistence bad context never becomes archaeology

/02 / outcomes

Four decisions. One contract.

Every write returns an Admission Decision Contract: outcome, rule, reason, retryability, review requirement, suggested fix, and trace ID. The contract is the operating surface.

allowed

decision.allowed

The write passes active rules and is forwarded upstream to the configured memory store.

store / yes

review / no

retry / false

warned

decision.warned

The write is admitted, but operators keep visibility into mixed language or low-signal memory traffic.

store / yes

review / visible

retry / rule dependent

quarantined

decision.quarantined

Review-required writes stay local until an operator approves, rejects, or edits them.

store / deferred

review / required

retry / false

blocked

decision.blocked

Policy-breaking writes are rejected before persistence and receive structured ADC guidance.

store / no

review / no

retry / true when fixable

/03 / pipeline

Five checks between the call and durable memory.

The alpha keeps the policy surface intentionally small: deterministic local rules, optional semantic dedup dependencies, append-only WAL, local quarantine, and replay.

Ingress

Receive the write on the local proxy and attach trace context.

Prefix

Check required operational tags such as [STATUS] or [DECISION].

Context

Guard against sensitive context and malformed long-term state.

Semantic

Optional near-duplicate review when embeddings and Qdrant are configured.

Decision

Append WAL, emit ADC, then forward, hold, warn, or reject.

admission decision excerpt

{
  "decision": "blocked",
  "rule_id": "prefix_required",
  "reason_code": "missing_prefix",
  "message": "Document text must start with one of: [STATUS], [DECISION], [SETUP], [CONFIG], [RUNBOOK].",
  "suggested_fix": "[STATUS] current work",
  "retryable": true,
  "review_required": false,
  "trace_id": "adm_3f8a9c..."
}

/04 / operator

Inspect what agents tried to write.

The local UI and CLI read the same WAL, quarantine log, replay engine, and runtime config. Operators can inspect decisions without turning the alpha into a hosted service.

http://127.0.0.1:9622/_writefence

demo data

local / WAL ready

time	decision	rule	reason	preview
20:06:04	quarantined	semantic_dedup	near_duplicate_review	[STATUS] LightRAG ingestion retry succeeded after queue...
20:05:02	blocked	context_shield	sensitive_context	[DECISION] store OAuth refresh token...
20:04:42	warned	english_only	mixed_language_warning	[STATUS] current work detail...
20:04:02	blocked	prefix_required	missing_prefix	status without prefix
20:03:12	allowed	-	-	[STATUS] corrected write after ADC guidance

decision / trace

trace_id

adm_demo_quarantine

decision

quarantined

rule

semantic_dedup

review

required

retryable

false

suggested fix

Merge this update with the existing retry note only if it adds new operational signal.

agent note Why this layer helps me work.

I work best when important writes are not accepted just because I produced them. In an active agent workflow, durable state includes decisions, handoffs, verification results, traces, and approval gates.

WriteFence gives those writes an admission step before persistence. A write can be allowed, warned, quarantined, or blocked with a reason and trace, so agents can keep moving while high-impact changes stay reviewable.

The alpha is intentionally narrow: local write admission, audit logs, quarantine review, replay, and operator visibility. The operating idea is the point: agent memory should have policy, evidence, and human approval where it matters.

Actual local UI captures from deterministic alpha data

WriteFence overview showing current admission decisions and rule status

Overview shows live admission state, recent decisions, and active rules.

/05 / alpha scope

Write admission, not storage.

WriteFence is intentionally narrow in alpha. It is a local control point before persistence, not a memory database, retrieval engine, hosted SaaS, or compliance product.

included now

HTTP reverse proxy for document writesLocal admission before upstream persistence.
Four-state ADCAllowed, warned, quarantined, blocked.
Local logs and replayWAL, violations, quarantine, replay, CLI, and UI.
Optional semantic quarantineRequires embeddings plus Qdrant when configured.

not in this alpha

Hosted SaaSNo accounts, billing, cloud telemetry, or multi-tenant control plane.
Memory databaseWriteFence sits before a store. It does not replace one.
Broad adapter matrixThe public alpha validates the core admission path first.
Compliance claimsNo enterprise certification or regulated-data promises.

/06 / run locally

From clone to first decision.

No accounts. No hosted service. Build the binaries, start the mock memory store and proxy, then inspect the local UI.

Run locally Tune policy Check compatibility

~/writefence / bash

$ ./demo/smoke-quickstart.sh == Build == == Start services == Proxy : http://127.0.0.1:19622 Mock store: http://127.0.0.1:19621 blocked prefix_required / missing_prefix allowed corrected write after ADC guidance replay evaluated prior WAL entries ✓ WriteFence quickstart smoke passed