Forgetting memories

Spectron distinguishes retiring memory (the agent stops using it) from erasing memory (the content is removed for compliance). Most day-to-day use is retirement; erasure is explicit and grant-gated.

All forget operations require the forget grant on the caller’s API key for the relevant scope. Keys with only read/write access cannot forget.

Semantic forget (default — retire, do not erase)

Describe what to remove in natural language. Spectron finds matching entities, facts, relations, and conversational chunks by semantic similarity, then expires them. Expired memory:

• Does not appear in /query, /profile, /state, or chat context going forward.

• Does remain in storage so you can audit what was retired and when, or review point-in-time history.

POST /api/v1/{context_id}/forget
Content-Type: application/json
API-KEY: sk-...

{
  "query": "anything about my old job"
}

{
  "deleted": 3
}

The response counts how many records were expired. Scope is enforced by the API key’s grants — you cannot forget outside the scopes your key is allowed to write (and forget) within.

spectron forget "anything about my old job" \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id "$SPECTRON_CONTEXT_ID"

Entity delete (default — retire one entity)

To target a specific entity by type and name:

DELETE /api/v1/{context_id}/entities/{entity_type}/{entity_name}

This expires the entity and its active facts and relations. Like semantic forget, it is a soft retirement by default — the entity no longer surfaces in retrieval, but the retired records remain stored.

Purge — permanent erasure (compliance)

When you must guarantee that content no longer exists in the memory substrate — for example a right-to-erasure request — use the same POST /forget endpoint with purge: true, or the CLI --purge flag.

POST /api/v1/{context_id}/forget
Content-Type: application/json
API-KEY: sk-...

{
  "query": "anything about my old job",
  "purge": true
}

With purge: true, Spectron permanently removes the matched entities, their fact history (including prior corrections), related relations, and linked conversational chunks. After a successful purge, that content is not recoverable from memory storage.

Audit note: the trace graph may still record that a forget call occurred (who, when, which operation) without retaining the deleted content itself. Plan your compliance story around both memory erasure and trace retention policies.

Purging is opt-in. Omitting purge (or setting it to false) keeps supersession history even after the current values are expired — the default path for ordinary agent memory management.

Scoped forget — erase a whole subtree

To remove everything tagged under a scope path (a user branch, team, or project subtree), use:

POST /api/v1/{context_id}/scopes/forget
Content-Type: application/json
API-KEY: sk-...

{
  "path": "user/alice/"
}

This hard-deletes all memory and knowledge records whose scope touches that subtree — entities, facts, sessions, documents, chunks, and related index state. It requires the forget grant over that subtree. The response reports how many rows were erased.

Use scoped forget for GDPR-style deletion when a principal’s entire branch must go, not just a single fact.

Choosing the right operation

After forget — extraction can bring facts back

Forget operates on what is stored now. If a later conversation turn mentions the same information again, extraction may create new memory for it. If you need a topic to stay gone, combine forget with product-level controls (do not re-ingest, block the source, or purge again).

Related reading

• Reconciliation and supersession — why corrections keep history by default

• Tri-temporal model — time-travel and belief history

• Scope as security boundary — forget grants

• REST API