Coding-Agent Memory

Persistent, governed project memory for a coding agent — the decisions, conventions, and gotchas it learns about your codebase, kept across sessions. For developers driving an agent in Claude Desktop, Cursor, or Cline.

What it is — agent memory that survives the session

A coding agent loses everything at each cold start: the decisions you made together, the conventions it learned to match, the traps it already hit once. The coding-agent-memory blueprint gives it a durable place to write those down and read them back — modeled as the facts/entities and episodic flavors of agent memory on Vectros. Each memory is a typed, schema'd record; recall is by meaning (HYBRID search) or by a stable key (exact lookup); and every change keeps a version history, so the agent can see not just what you decided but how the decision evolved.

What bootstrap provisions

Running the blueprint stands up everything below in one shot — no application code.

  • Three schemas, each HYBRID-indexed (keyword on titles + semantic on the prose body):
    • decision — a durable architectural/product decision. Fields: title (required), statement (what was decided), rationale (the why — the highest-value, most-recalled field), status (proposed | active | superseded), area, decidedOn (ISO-8601), and externalId (required, the caller-stable upsert key). Lookups: externalId (unique — exact get/upsert) plus non-unique area and status, so the agent can enumerate a slice directly ("all active decisions", "decisions in the auth area") without a search.
    • convention — a coding convention the agent reads before it writes code. Fields: name (required), rule (stated as an imperative), area, status (active | retired), adoptedOn (ISO-8601), and externalId (required). Lookups: externalId (unique) + non-unique area/status — enumerate "active conventions for auth".
    • gotcha — a sharp edge: symptom (required), cause, fix, area, status (active | retired), discoveredOn (ISO-8601), and externalId (required). Lookups: externalId (unique) + non-unique area/status.
  • A least-privilege access profile — allowedActions is exactly records:r, records:c, records:u, search:r, schemas:r. Note the deliberate absence of records:d: every memory type carries a status, so a decision is superseded, a convention or gotcha retired — never deleted, keeping the full audit trail of how the project's thinking changed.
  • A service principal — externalId coding-agent-memory, the identity the agent's key acts as.
  • A seed record — one decision (seed-use-vectros-for-memory) that explains why the project uses Vectros as its memory, so the store is never empty on first recall.

The whole apply is idempotent: re-running converges on the same state rather than duplicating, because every record is keyed by its externalId.

Before you start

This is an invite-only 0.x preview, so the honest prerequisites: you need an early-access invite, and from the dev portal you mint a short-lived Cognito bridge token — that human step authenticates the CLI before it can provision anything. You also need Node (the CLI and MCP server run via npx). That's it; once you have the bridge token in hand, the rest is two commands and a config merge.

1. Bootstrap the blueprint

# install once: npm i -g @vectros-ai/cli  (or use npx @vectros-ai/cli, below)
npx @vectros-ai/cli bootstrap --blueprint coding-agent-memory

End to end, this provisions the three schemas, creates the app-context, registers the service principal, gates and creates the least-privilege access profile, mints a narrow scoped key (an ssk_*) carrying exactly the five data-plane actions above, and writes the seed record. The minted ssk_* is auto-merged into your Claude Desktop config so your agent can use it immediately — for Cursor, Cline, or any other MCP client, pass --print and paste the printed mcpServers.vectros block into that client's MCP config. Because the access profile is gated to data-plane actions only, the key can never touch keys, profiles, app-contexts, users, or billing.

2. Give it to your agent (no code)

After bootstrap, your MCP client (Claude Desktop, Cursor, Cline) points at the Vectros MCP server with the new ssk_*. The agent now drives the store through the server's data-plane tools — entirely in natural language. A few interactions:

  • "Remember we decided to use cursor-based pagination because offset pagination drifts under concurrent writes." → the agent calls record_create with typeName: decision, a title, the statement, the rationale, status: active, and a stable externalId.

  • "What did we decide about pagination?" — in a fresh session, with no prior context. → the agent calls hybrid_search to recall by meaning across statement/rationale — optionally narrowing with filters on the filterable fields (e.g. status: active). It reads back the decision it never would have remembered on its own.

  • "List every active decision" / "show me all the gotchas in the auth area" — enumerate a slice, no semantic query. → the agent calls record_query in lookup mode on a non-unique lookup field (field: status, value: active, or field: area, value: auth), or in list mode (by typeName, no field) to page through every record of a type. This is the direct, deterministic counterpart to hybrid_search — memory needs both: search to recall by meaning, lookup/list to enumerate a known slice. (And record_query by externalId fetches one decision exactly.)

  • "That decision changed — we're moving to keyset pagination now." → the agent calls record_update on the same externalId: it can flip the old decision's status to superseded and record the new one, leaving both in the history.

Discovery is free too: the agent can call list_schemas to learn the decision / convention / gotcha shapes before it writes, so it fills the right fields.

3. See it work

The "aha" is cold-context recall. Open a brand-new agent session — no memory of the earlier conversation — and ask "why are we using cursor-based pagination?". The agent runs a hybrid_search, finds the decision record by meaning, and answers with the original rationale it captured weeks ago. Then ask it to show how that decision evolved: the version history surfaces the earlier active revision and the later superseded one, with the timestamps of each write. The agent didn't re-derive the answer — it remembered it, and can show its work.

How it maps to Vectros

  • Typed, schema'd records — decision / convention / gotcha are real schemas with typed, validated payloads, not free-text blobs.
  • HYBRID search — every schema is indexMode: HYBRID, so recall is keyword on titles and semantic on the prose body.
  • Lookup and search — both access patterns, one schema — externalId (unique) gives exact get + idempotent upsert; non-unique area/status lookups let the agent enumerate a slice via record_query; HYBRID search recalls by meaning. Memory needs both the "find what I mean" and the "list what I have" paths.
  • Version history — every write keeps an immutable prior revision, so a superseded decision stays visible alongside its successor.
  • Scoped key — bootstrap mints a narrow ssk_* with exactly five data-plane actions; the absence of records:d is enforced, not just a convention.
  • MCP, no code — the agent drives the whole thing through record_create, record_query, hybrid_search, record_update, and list_schemas.

Notes & limits

  • Synthetic / non-secret data only for this preview — record decisions and conventions, not secrets or production credentials.
  • The bridge-token step is a real human prerequisite — you mint a Cognito bridge token from the dev portal before bootstrap; it isn't automated away.
  • Data-plane tools only. The MCP server exposes records/schemas/search/document tools — there is no web-fetch or web-search tool, by design. The agent's memory is what you've written to Vectros, nothing it pulls from the open web.
  • No delete. The blueprint's key carries no records:d. Decisions are superseded, never removed — that's the point, and it's also a hard scope limit.
  • Audit is tamper-evident, not tamper-proof. Writes are recorded with a SHA-256 state-continuity chain you can inspect for tampering; continuous automated verification is not yet part of this preview.