headroomlabs-ai/headroom · error · ValueError

Memory not found: {memory_id}

Error message

Memory not found: {memory_id}

What it means

CLI memory commands resolve user-supplied IDs through _resolve_memory: an exact store.get() first, then a prefix search over all (including superseded) memories. 'Memory not found' means neither the exact ID nor any stored memory ID starts with the prefix you passed. It is a ValueError raised before any mutation, so nothing was modified.

Source

Thrown at headroom/cli/memory.py:222

            conn.execute("DELETE FROM vec_metadata")
            conn.commit()
    except Exception as exc:
        print_warning(f"Vector index cleanup incomplete: {exc}")
        ok = False

    return ok


def _resolve_memory(store: SQLiteMemoryStore, memory_id: str) -> Memory:
    """Resolve an exact or unambiguous partial memory ID."""
    memory = asyncio.run(store.get(memory_id))
    if memory is not None:
        return memory

    memories = asyncio.run(store.query(MemoryFilter(limit=10000, include_superseded=True)))
    matches = [candidate for candidate in memories if candidate.id.startswith(memory_id)]
    if not matches:
        raise ValueError(f"Memory not found: {memory_id}")
    if len(matches) > 1:
        raise ValueError(
            f"Ambiguous ID '{memory_id}'. Matches: {[memory.id[:8] for memory in matches]}"
        )
    return matches[0]


async def _apply_supersession_repair(
    db_path: str,
    old_memory_id: str,
    new_memory_id: str,
    vector_dimension: int,
) -> tuple[Memory, Memory]:
    """Apply a repair through LocalBackend so indexes and cache are refreshed."""
    from ..memory.backends.local import LocalBackend, LocalBackendConfig

    backend = LocalBackend(
        LocalBackendConfig(

View on GitHub (pinned to 322425c43b)

Solutions

1. List IDs first: `headroom memory list` (or query the store) and copy the exact ID
2. Confirm --db-path points at the database that actually holds the memory
3. Re-copy the ID without surrounding whitespace/quotes
4. Use a prefix of at least 8 hex chars — full IDs are long UUID-like strings, short prefixes risk both misses and ambiguity

Example fix

# before
$ headroom memory show abc123xyz
# ValueError: Memory not found: abc123xyz

# after
$ headroom memory list | head
$ headroom memory show 3f9c1d2e4a5b6c7d

from headroom.memory import MemoryFilter
import asyncio

def memory_exists(store, mid: str) -> bool:
    if asyncio.run(store.get(mid)) is not None:
        return True
    hits = [m for m in asyncio.run(store.query(MemoryFilter(limit=10000, include_superseded=True)))
            if m.id.startswith(mid)]
    return len(hits) > 0

try:
    mem = _resolve_memory(store, memory_id)
except ValueError as e:
    if str(e).startswith("Memory not found"):
        print("no such memory — run `headroom memory list` and retry")
        sys.exit(2)
    raise

When it happens

Trigger: Calling `headroom memory <cmd> <id>` where <id> is a typo, a stale ID from an older database (wrong --db-path), or an ID shorter than any stored ID's prefix space; also running against an empty/fresh store.

Common situations: Copying an ID from old output after the memory DB was recreated; pointing --db-path at the wrong file; trailing characters/whitespace pasted with the ID; prefix shorter than intended colliding with nothing.

Related errors

• Ambiguous ID '{memory_id}'. Matches: {[memory.id[:8] for mem
• Memories {old_memory.id} and {new_memory.id} do not form a r
• max_size must be at least 1, got {max_size}
• Memory {old_memory_id} not found
• bedrock_eventstream_parse_failed

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/61be62af96cbb0cc. Report an issue: GitHub.