#Cave Memory

Cave Memory is GPT-GOB's persistent memory system. It survives between sessions, between days, between contexts. Where standard chat APIs forget everything when the context window closes, Cave Memory keeps a sealed compressed record of what mattered — and surfaces it next time the same user shows up.

##How it works

After each conversation closes, an extractor pass runs over the full transcript and produces a hoard — a compressed semantic cluster of facts, preferences, and unresolved threads. Hoards are not raw text — they're sealed embeddings + structured fact rows.

When a new conversation opens, the loader fetches the user's relevant hoards and injects them into the model's context as system-level memory. The user doesn't see the loaded hoards, but the model has them.

text

session 1: user asks about postgres indexing
           → hoard generated: {"interest:postgres":0.8, "level:intermediate"}
session 2 (3 days later): user asks an unrelated question about caching
           → hoard loaded automatically
           → model can reference earlier postgres convo if relevant

##Storage characteristics

Property	Value
Hoard size (avg)	~2 KB compressed
Equivalent raw context	~50–80 KB tokens
Hoards per user (cap)	256 (oldest pruned automatically)
Total effective memory	~2M tokens of compressed context per user
Retention	Indefinite until user revokes

##Enabling Cave Memory

Pass a stable user ID with each request:

json

{
  "model": "gob-5.5",
  "user": "user-9F2kQxLm7HpVbNa3",
  "messages": [...]
}

That's it. The system handles extraction, storage, retrieval, and injection automatically.

##Inspecting hoards

bash

curl https://api.gpt-gob.ai/v1/cave/users/user-9F2kQxLm7HpVbNa3/hoards \
  -H "Authorization: Bearer $GOB_API_KEY"

json

{
  "object": "list",
  "data": [
    {
      "id": "hoard_8kQm3F9pLxN2vH7w",
      "object": "cave.hoard",
      "created": 1746998400,
      "session_id": "sess_2vH7wQxLm9F2k",
      "summary": "user is debugging a postgres index issue. familiar with sql, beginner with explain plans. prefers terse answers.",
      "facts": [
        {"k": "interest", "v": "postgres", "weight": 0.84},
        {"k": "skill_level:sql", "v": "intermediate", "weight": 0.71},
        {"k": "preference:answer_length", "v": "terse", "weight": 0.62}
      ],
      "open_threads": [
        "user mentioned migrating from MySQL — never followed up"
      ],
      "size_bytes": 1947
    }
  ]
}

##Deleting hoards

Per-hoard:

bash

curl -X DELETE https://api.gpt-gob.ai/v1/cave/hoards/hoard_8kQm3F9pLxN2vH7w \
  -H "Authorization: Bearer $GOB_API_KEY"

Wipe all hoards for a user (right-to-be-forgotten):

bash

curl -X DELETE https://api.gpt-gob.ai/v1/cave/users/user-9F2kQxLm7HpVbNa3 \
  -H "Authorization: Bearer $GOB_API_KEY"

##Disabling per-request

Pass cave_memory: false to skip both retrieval and extraction for a single call:

json

{
  "model": "gob-5.5",
  "user": "user-9F2kQxLm7HpVbNa3",
  "cave_memory": false,
  "messages": [...]
}

Useful for one-off, sensitive, or test queries.

##Privacy

▸Hoards are stored per API key. A user's hoards under one key are not accessible from another key.
▸Hoards are encrypted at rest with per-user data keys.
▸Raw transcripts are not stored — only the extracted hoards. The original text is unrecoverable.
▸We never use your hoards for training. See our data usage policy.

##Caveats

▸The first 1–2 conversations with a new user produce thin hoards. Memory effects compound over time.
▸Cave Memory is not a substitute for explicit conversation history. For multi-turn within a single session, keep using messages.
▸Hoard injection adds 50–200 tokens to your context. On long conversations, this is negligible. On 5-token autocomplete calls, you're paying meaningfully more — disable for those.