JuliusBrussee/caveman · warning

cave_memory_too_large

cave_memory_too_large

Error message

cave_memory_too_large

What it means

mem.Store rejects any memory whose text exceeds MaxMemoryBytes (256 KiB), returning the sentinel ErrMemoryTooLarge which carries the cave_ error idiom. It fails closed so oversized memories are never stored and never blow the recall budget later. Callers surface it as the MCP tool error cave_memory_too_large or as a dedicated CLI exit code.

Solutions

1. Trim or chunk the text below 256 KiB before calling Remember (store an excerpt or split into multiple memories).
2. Compress/summarize the content before storing.
3. Check len([]byte(text)) (or utf8.RuneCountInString for per-memory semantics) client-side and reject early with a better message.
4. If legitimately larger memories are required, raise the limit consciously at deployment knowing recall budget grows.

Example fix

// before
m, err := store.Remember(bigText)
// after
if len(bigText) > mem.MaxMemoryBytes {
    bigText = summarize(bigText)
}
m, err := store.Remember(bigText)

if len([]byte(text)) > mem.MaxMemoryBytes {
    return fmt.Errorf("memory is %d bytes, limit is %d", len(text), mem.MaxMemoryBytes)
}

m, err := store.Remember(text)
if errors.Is(err, mem.ErrMemoryTooLarge) {
    text = summarize(text)
    m, err = store.Remember(text)
}

When it happens

Trigger: store.Remember(text) (and supersede paths validated by validateMemorySize) called with text longer than 256*1024 bytes; the MCP remember tool in mem/cmd/cavemem/main.go:126 and the remember CLI command at main.go:254 map this error to tool error/exit code.

Common situations: Pasting a large document/log into a remember call; agent pipelines dumping whole files as memories; a supersede replacement bigger than the limit; unicode-heavy text where character count misleads about byte size.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• githubapp: repository proof size mismatch
• SKILL.md must be 1..262144 bytes
• telemetry attributes exceed
• : bytes (limit )
• : memory is bytes, over the -byte cap

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/64c2d31821ecd040. Report an issue: GitHub.

Appendix: source

Thrown at mem/store.go:71

// across all its hits. Without it, recall loaded and returned every matching
// memory whole — a single 2.5 MB memory came back as tokens_added=440,000 in one
// result. Callers override it per-call through RecallOptions.TokenBudget.
const DefaultTokenBudget = 2000

// UnlimitedTokenBudget disables Recall's aggregate token cap. It is explicit:
// zero retains the safe DefaultTokenBudget for existing Go callers. Public
// adapters map their documented token_budget=0 sentinel to this value.
const UnlimitedTokenBudget = -1

// MaxMemoryBytes is the largest single memory Remember accepts. A memory is a
// fact or note meant to be recalled and injected, not a file dump; anything
// larger fails closed with ErrMemoryTooLarge rather than being stored and later
// blowing the recall budget.
const MaxMemoryBytes = 256 * 1024

// ErrMemoryTooLarge is returned when new memory text exceeds MaxMemoryBytes.
// It carries the cave_ error idiom so callers surface cave_memory_too_large.
var ErrMemoryTooLarge = errors.New("cave_memory_too_large")

// tokenCounter is the shared offline BPE estimator (o200k_base). It is read-only
// and safe for concurrent use, matching the engine's inferred token accounting.
var tokenCounter = tokens.Default()

// Store is a cavemem instance: a SQLite memory table plus an engine (with its
// own CCR store) used to compress recalls.
type Store struct {
	db  *sql.DB
	eng *engine.Engine
	ccr *ccr.Store
}

// Options configures Open.
type Options struct {
	// Dir is the data directory; default ~/.caveman/mem (honoring CAVEMAN_HOME).
	Dir string
	// InMemory uses an ephemeral database for both memories and CCR (tests).

View on GitHub (pinned to 3ee70a1026)