Proposal: Icebug agent-memory starter helpers

[mvanhorn]

Motivation

Social/YouTube gravity around Ladybug is agent memory and GraphRAG, while Icebug-Disk (#504 / docs) is an object-storage-friendly immutable graph format. New users lack a starter schema and helpers that map episode/entity/relation memory onto Icebug without inventing a competing product.

Research Summary

Evidence Vault

• last30days: Icebug + agent memory/GraphRAG.
• docs/icebug-disk.md covers format, not agent patterns.
• Discussion Icebug format design discussion #504 is format design, not memory helpers.

Proposed Solution

Ship an examples/agent_memory starter:

1. schema.cypher for Episode, Entity, Mention, Relation node/rel tables on format='icebug-disk'.
2. README showing load from object-store URI, a minimal GraphRAG-style retrieve query, and honesty about immutability (rebuild/publish new snapshots).
3. Optional tiny Python/CLI snippet under examples (stdlib or existing bindings) that writes Parquet slices compatible with Icebug layout — or documents using the icebug-format converter.
4. Cross-link from docs/icebug-disk.md and a short docs/agent-memory.md.

No new engine subsystem in v1; example + docs grade unless maintainers want a thin helper extension later.

Approach

Ideas Discussion to confirm schema nouns and whether examples-only is enough.

Test Strategy

CI-friendly check that schema.cypher parses / example README commands are dry-run documented; optional e2e if test data fixtures exist.

Alternatives Considered

• Full vector+graph memory engine: too large.
• Only a blog post outside the repo: weaker discoverability.

PR Strategy

Ideas first; then examples/docs PR.

Happy to open a draft PR if this shape looks right. Looking for maintainer signal before writing code.

[adsharma]

@mvanhorn are you looking for something like this?

https://github.com/Ladybug-Memory/ladybug-memory (Right now ladybug only, no icebug here)

https://github.com/Ladybug-Memory/icebug-skill/
https://github.com/LadybugDB/ladybug-skill

may be useful for building out such an example app.

GitNexus has an example implementation for code knowledge graphs:

abhigyanpatwari/GitNexus#2337

I have a prototype quality implementation for Graphify as well using the two skills above.

icebug-format is necessary only when the data doesn't fit on a single machine and/or when you want to use a SQL engine such as duckdb and datafusion to query the data (those engines can't query native ladybug databases, but can query icebug-format since the data is held in parquet files).