mcp-assist-memory

A generic, project-agnostic memory / coordination / artifact server for multi-agent and multi-surface work. One FastAPI process serves a 30-tool MCP over Streamable HTTP, backed by Postgres (+ pgvector), deployed standalone on a Replit Reserved VM.

This is Tier 1 of the reusability contract: every project reuses it as-is. It carries zero domain terms — project identity lives in namespace values, never in tool names, tables, columns, or code.

Capabilities at a glance

• 30-tool MCP over Streamable HTTP (memory, handoff, session, artifact, coordination, feedback, admin).
• Trust-boundary spine (Plan v2) — actor-scoped exactly-once writes with visible dedup, read-back-verified acks (verified_persisted), standardized error payloads with remedies, write-time screening + quarantine, provenance tiers (origin, model attribution, derived_from lineage), trust decay (needs_reverification), PHI-safe tool_events telemetry, per-namespace variant profiles, and an observation_log feedback channel.
• Namespace-scoped multi-tenancy — every per-project query filters on namespace.
• Resilient to transient DB drops — the server transparently retries genuine connection losses (Neon scale-down / PgBouncer recycle, SQLSTATE 57P01/08xxx) on a fresh pooled connection, and validates connections at checkout, so callers no longer have to retry. Retries are idempotency-gated, so they never double-write.
• Prompt-injection resistance layer — values are sanitized on write (forged markers are escaped one-way to [[UNTRUSTED_DATA]], never reconstructed on read), instruction-shaped writes are screened and quarantined (visible in the write ack; include_quarantined: true opts reads back in), and reads come back wrapped in <<<UNTRUSTED_DATA>>> markers; storage.sanitize.unwrap_value recovers the raw value when a consumer needs it (e.g. to json.loads). Honest framing: these are layers, not proofs — deterministic screens and wrappers are bypassable by an adaptive attacker; adversarial evaluation is pending (see Phase 10 backlog in DECISION-PROTOCOL.md).
• Content-addressed artifacts (sha256, global dedup), 50 MB cap, ranged reads.
• Per-surface rotatable tokens (web vs. desktop-cli) managed from a password-gated /admin dashboard.

The 30 tools

Sequences are the paths an agent should take. Correct use of this server has always been a sequence — learn which database answered, resolve the profile, check what is stale, then act — and that ordering used to live in tool descriptions and skills, i.e. it was enforced by a model remembering advice mid-task, and a skipped step produced no signal whatsoever. The three sequence tools run their steps server-side in a fixed order and return steps_run, so the ordering is something the server did rather than something a caller got right. They are strictly additive: every primitive they are built from still works exactly as before, for surgical use.

recall and memory_search now share ONE retrieval guard (storage/retrieval.py): the same absolute floor and relative alpha the Intent Gate applies. Previously memory_search had no floor at all while intent_open had both, so the same store answered the same question differently depending on which tool the caller reached for. They still differ in what they do with the verdict — memory_search annotates every row and drops nothing, recall filters by default and reports the rejected counts — but they can no longer disagree about what counts as a match.

The Intent Gate (claude/intent-gate/INTENT_GATE_CHARTER.md) is a per-namespace opt-in (variant_profiles.profile.intent_gate: "on"): mutating tools gain a deterministic Tier-0 pre-flight (two-phase preview/confirm for supersession + delete, dependency-freshness flags, compact gate ack block), intent_open adds the Tier-1 memory-similarity critic, and Tier 2 (LLM reasoning over the direct Anthropic API — never MCP sampling) ships behind tier2: "on" (default off). Default-profile namespaces are byte-identical to the pre-gate server.

/healthz (liveness) and the /admin token dashboard are served separately (not MCP tools).

Tenancy — namespace is the project boundary

namespace == project == tenant. One namespace per project (e.g. acme-billing), with conventional sub-scopes by key prefix (coord/…, knowledge/…). Every per-project tool takes a required namespace and every query filters on it — there are no implicit cross-project reads. The session and session_event tables carry namespace too, so episodic memory is scoped like everything else.

Artifacts are the deliberate exception: they are content-addressed (sha256) and dedup globally, so they are not tenant-scoped — the hash is the capability.

Honest limit (and the v2 fix)

The per-surface tokens scope which client surface connects, not which project it may touch: any holder of any active token can pass any namespace, so namespace remains a soft boundary — real isolation for honest clients, not enforced against a misbehaving one.

v2 auth roadmap — per-project tokens/roles. A token scoped to acme-billing must not be able to read or write other-project. Until then, treat the namespace boundary as a convention enforced by client configuration, not by the server. (See REUSABILITY.md → "namespace is the tenant boundary".)

Auth & the /admin dashboard

MCP tokens are stored in Postgres (admin_auth_tokens) and rotatable from /admin without a redeploy. There is one active token per surface:

The gate accepts any active token, so each surface can be rotated or revoked independently — rotating web never disturbs desktop-cli or cursor. The /admin page shows one card per surface with a ready-to-paste URL/command and its own rotate button.

MCP_AUTH_TOKEN seeds the web token on initial boot (so an existing claude.ai connector keeps working); desktop-cli and cursor are auto-generated. After first boot the dashboard is the source of truth.

• /admin is password-gated by ADMIN_PASSWORD (signed, HttpOnly session cookie, CSRF-protected). Without it the dashboard refuses logins.
• The only routes not behind the bearer gate are GET /healthz, the streamed GET /artifact/{sha256}, and /admin (which self-authenticates).

Stateless transport. /mcp runs in stateless HTTP mode (http_app(stateless_http=True)): every request is self-contained, with no in-memory session affinity. Client sessions therefore survive VM restarts/redeploys, and the three surfaces share no server-side session state.

Architecture