View as Markdown

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, and decidedOn (date). Lookups: non-unique area and status (equality — "all active decisions", "decisions in the auth area"), plus a decidedOn range index ("decisions made this quarter"). Each record also carries a first-class externalId — the caller-stable dedup/upsert key and the value other records reference — sent top-level, not a declared field or lookup.
    • convention — a coding convention the agent reads before it writes code. Fields: name (required), rule (stated as an imperative), area, status (active | retired), establishedByDecision (a typed reference to the decision that established it), and adoptedOn (date). Lookups: area/status and establishedByDecision (equality — enumerate "active conventions for auth", or "conventions established by decision X"), plus an adoptedOn range index.
    • gotcha — a sharp edge: symptom (required), cause, fix, area, status (active | retired), and discoveredOn (date). Lookups: area/status (equality) plus a discoveredOn range index.
  • A least-privilege access profile — allowedActions is exactly records:r, records:c, records:u, search:r, schemas:r, inference:r. The inference:r scope powers grounded "why did we decide X?" recall (rag_ask) over the captured rationale. 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.
  • Two seed records — one decision (seed-use-vectros-for-memory) explaining why the project uses Vectros as its memory, and one convention (seed-record-the-why) that references that decision — a live typed link the moment the blueprint applies, so the store is never empty and the cross-type relationship is visible from the start.

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 six data-plane actions above, and writes the seed records. 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.

  • "Record a convention for this, and link it to the decision behind it." → the agent calls record_create for a convention with establishedByDecision set to the decision's externalId. Because it's a typed reference, the platform verifies that decision exists before accepting the write, and you can later enumerate "conventions established by this decision" via the establishedByDecision lookup. (Link at runtime, not in the seed — the target is already indexed by then.)

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 + grounded rag_ask — every schema is indexMode: HYBRID, so recall is keyword on titles and semantic on the prose body; with inference:r the agent can ask "why did we decide X?" and get a grounded, cited answer over the captured rationale.
  • Lookup and search — both access patterns, one schema — non-unique area/status lookups let the agent enumerate a slice via record_query; HYBRID search recalls by meaning (externalId has a built-in finder for exact get + idempotent upsert). Memory needs both the "find what I mean" and the "list what I have" paths.
  • Ordered range lookups — each schema's date field (decidedOn / adoptedOn / discoveredOn) is range-indexed, so the agent can pull "decisions made this quarter" without a search.
  • Typed references between record types — convention.establishedByDecision is a typed link to the decision that established it (the platform enforces the target exists at write). Provenance as a first-class edge: "why does this convention exist? → open the decision behind it." Add the reference field as an equality lookup to enumerate "conventions from decision X" (the reverse-direction query isn't exposed here).
  • 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 six 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, rag_ask, 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.