icelake
Accurate, scalable, cost-effective agentic memory for Discord bots — ChatGPT/Claude-style memory of your users, hardened against cross-user attribution errors, working across every member of a server.
Priority order (non-negotiable): Accuracy → Cost → Performance.
- Accurate: facts attach to hardened Discord user IDs via a roster-token protocol that structurally prevents LLM hallucinated attribution; third-party statements ("X called Y a hacker") anchor on the person they're about, with the speaker kept as attribution.
- Cost-effective: batched extraction (~1 LLM call per ~10 messages), conditional reconciliation (phase-2 fires only on collisions), zero-LLM retrieval, pluggable embeddings.
- Scalable: durable lease queue safe across processes, guild-partitioned storage, hub-aware bounded graph traversal, per-guild budgets with graceful degradation.
- Composable: every external dependency sits behind a Protocol port — swap storage, LLM provider, embedder, or clock with one constructor argument.
Install
pip install icelake # core (SQLite backend, hashing embedder)
pip install "icelake[discord]" # + discord.py integration
pip install "icelake[mongo]" # + MongoDB backend (PyMongo Async)
pip install "icelake[local-embeddings]"# + sentence-transformers embeddings
Requires Python ≥ 3.12.
Quickstart
import asyncio
from datetime import UTC, datetime
from icelake import DiscordMemory, MemoryConfig, MessageEvent
async def main() -> None:
memory = DiscordMemory(MemoryConfig(
storage="sqlite:///memory.db",
llm="openai://$OPENROUTER_API_KEY@openrouter.ai/api/v1"
"?model=google/gemini-3.7-flash",
))
async with memory:
# 1. Feed it messages (fire-and-forget; extraction happens in background)
receipt = await memory.observe(MessageEvent(
message_id="9001", guild_id="555", channel_id="777",
author_id="100000000000000001",
content="I've been learning Rust for about a year now!",
created_at=datetime.now(UTC),
author_display_name="alice",
))
# 2. Build prompt context for a reply: asker + mentioned users + server.
ctx = await memory.prompt_context(
guild_id="555",
asker_id="100000000000000001",
text="what am I learning these days?",
mentioned_ids=("200000000000000002",), # @mentions in this message
)
print(ctx.injection_block) # labeled, budgeted, cite-tagged block
# 3. After generation, resolve echoed [mem:N] tags into jump links.
reply = ctx.apply_citations("You're learning Rust [mem:1]!")
asyncio.run(main())
Runnable, complete examples live in examples/:
| File | What it demonstrates |
|---|---|
examples/omni_style_bot.py |
Production-shaped bot: passive learning, ping/reply turns, /memory slash group, OpenRouter chat + embeddings |
examples/ping_reply_bot.py |
Classic chat bot: observe every message, reply when pinged, citations, remember/forget, nickname tracking |
examples/relationship_queries.py |
Zero-LLM graph demo: 8 members, pair recall, stances, 2-hop neighbors. No Discord required |
examples/e2e_simulation.py |
Public-API eval: 81 hard invariants + model expectations against a scripted guild |
examples/bench_models.py |
Parallel model matrix; writes JSON + Markdown reports |
The ping-reply turn, step by step
When @Bot what happened between alice and bob? arrives:
# 1. Resolve memories for EVERYONE in the conversation in one call:
ctx = await memory.prompt_context(
guild_id=guild_id,
asker_id=str(message.author.id), # who is talking -> their profile
text=question, # query + entity hints
mentioned_ids=("alice_id", "bob_id"), # referenced users' profiles
)
# ctx.injection_block is labeled so facts never bleed across users:
#
# [MEMORY CONTEXT]
#
# WHAT I KNOW ABOUT THE CURRENT ASKER
# Facts about the asker ONLY:
# - [mem:1] alice mains support in every ranked game she plays
#
# REFERENCED USER: bob
# Facts about bob ONLY. Do NOT attribute these to the asker.
# - [mem:2] bob was called a hacker by alice during the ranked match
#
# SERVER COMMUNITY FACTS
# Community-wide traits:
# - [mem:3] the community bonds over late night gaming sessions
#
# When you use a fact above in your reply, echo its [mem:N] tag ...
# 2. Generate your LLM reply using system_prompt + ctx.injection_block.
# 3. Resolve echoed tags into jump links (deleted-message safe):
reply = ctx.apply_citations(reply_text)
# "... bob was called out [[mem:2]](https://discord.com/channels/...)"
Cross-user questions ("what does X think about Y")
Names resolve through the alias ladder (mention ID / username / display name / saved real name); ambiguity never guesses:
resolution = await memory.identity.resolve(guild_id, "klim") # or snowflake/@mention
if resolution.ambiguous:
... # ask which member; never guess
edges = await memory.graph.between(guild_id, x_id, y_id) # typed edges
stances = await memory.graph.entity_stances(guild_id, "movies") # opposing stances co-presented
neighbors = await memory.graph.neighbors(guild_id, x_id, depth=2) # hop discovery w/ paths
similar = await memory.graph.similar_users(guild_id, x_id) # Jaccard over traits
Chat-native commands (ChatGPT style)
command = await memory.classify_command("hey bot remember that I hate pineapple")
# UserMemoryCommand(action="remember", target_text="that I hate pineapple", confidence=0.9)
if command.action == "remember":
await memory.facts.remember(
guild_id=guild_id, subject_id=user_id,
text=command.target_text, actor_id=user_id,
)
Manual facts accept graph participation too:
from icelake.models.operations import ProposedRelation
await memory.facts.remember(
guild_id=guild_id, subject_id=bob_id,
text="carol called bob a sore loser during game night",
actor_id=carol_id, speaker_id=carol_id, # third-party attribution
relations=(ProposedRelation(
verb="called_out", from_token=carol_id, to_token=bob_id),),
)
Governance every production bot should wire
@bot.command()
async def forgetme(ctx: commands.Context):
await memory.admin.purge_user(str(ctx.guild.id), str(ctx.author.id),
dry_run=False)
await ctx.reply("All memories about you have been purged.", mention_author=False)
# opt-out is enforced instantly across observe AND recall:
await memory.admin.set_opt_out(guild_id, user_id, True)
Full usage documentation: docs/USAGE.md · Complete API contract:
docs/API.md · Design: docs/PLAN.md · What ships next:
docs/ROADMAP.md.
Full bot example (omni-style)
For a production-shaped deployment — passive learning for everyone, replies only when
addressed, requester-first multi-person context, /memory slash group, governance — see
examples/omni_style_bot.py. It mirrors the architecture of
a memory-native production bot and wires OpenRouter for both chat (google/gemini-3.7-flash)
and embeddings (openai/text-embedding-3-small) so reconcile collisions and recall work on
paraphrases, not just exact text matches.
- Composition root:
build_memory()is the single place config → adapters → client get wired; everything else receivesmemory. - Learn from everyone, answer the addressed:
on_messageobserves every message (bots included — they're registered as never-a-subject), then answers only when pinged or replied to. - Requester-first turn context (capped at 4 subjects): asker + @mentions + reply-target,
resolved in one
prompt_contextcall with per-person labeled sections. - Coreference lines: members known by several names get an explicit "these names all refer to ONE person" line so the model never splits them.
/memorygroup:show(profile w/ aliases),related(typed edges),shared(common entities),edit(teach a fact),alias(teach a nickname).- Governance built in:
/forgetme,/optout, daily guild budgets, health.
class OmniStyleBot(commands.Bot):
def __init__(self, memory: DiscordMemory) -> None:
...
self.memory = memory
@commands.Cog.listener()
async def on_message(self, message: discord.Message) -> None:
if message.guild is None:
return
await self.memory.observe(to_event(message)) # learn; never blocks
if message.author.bot:
return
if await self._is_addressed(message): # ping or reply-to-us
await self._handle_turn(message)
async def _handle_turn(self, message: discord.Message) -> None:
question = strip_bot_mention(message.content, self.user.id).strip()
subjects = await self._collect_subjects(message) # mentions + reply target
ctx = await self.memory.prompt_context(
guild_id=guild_id,
asker_id=str(message.author.id),
text=question,
mentioned_ids=tuple(subjects),
token_budget_tokens=800,
)
system_prompt = PERSONA + "\n\n" + ctx.injection_block
reply = await generate(system_prompt, history, question)
await message.reply(ctx.apply_citations(reply)[:1900], mention_author=False)
The injection block a turn produces looks like:
[MEMORY CONTEXT]
REFERENCED USER: bob
Coreference: these names all refer to ONE person: bob, bobert, bobby.
Facts about bob ONLY. Do NOT attribute these to the asker.
- [mem:1] bob was called a hacker by alice during the ranked match
SERVER COMMUNITY FACTS
Community-wide traits:
- [mem:2] the community bonds over late night ranked gaming sessions
When you use a fact above in your reply, echo its [mem:N] tag so the user
can see the source. Do not invent tags for facts that were not listed.
How it works
flowchart TB
observe["observe(event)"] --> queue["Pending message queue"]
queue --> worker["Lease worker<br/>one claim per guild + author"]
worker --> noise{"Noise gate"}
noise -->|chatter| skip["Ack - no LLM"]
noise -->|worth extracting| roster["Mint roster tokens<br/>p0, p1, server"]
roster --> extract["LLM extraction"]
extract --> schema{"Valid JSON schema?"}
schema -->|no after one repair| dead["Dead-letter the batch"]
schema -->|yes| gates["Quality gates"]
gates --> hit{"Near-duplicate collision?"}
hit -->|no| add["ADD fact"]
hit -->|yes| recon["Reconcile LLM"]
recon --> add
recon --> history["SUPERSEDE or INVALIDATE<br/>history kept"]
add --> store["Fact store<br/>bitemporal, one subject anchor"]
add --> vectors["Vector index"]
add --> kg["Knowledge graph<br/>incidence + typed edges"]
add --> digest["Profile digest<br/>every N new facts"]
observe is fire-and-forget: persist + enqueue, then return. Workers claim with keyed
leases so multiple processes cannot double-extract the same author. Invalid extraction
JSON is repaired once, then dead-lettered rather than silently acked empty.
Accuracy model
- Roster-token protocol — identity fields (
subject_token,speaker_token, relation endpoints) may only use tokens we minted for this batch (p0,p1,server). The model never sees Discord snowflakes; unknown tokens are dropped. Stored prose uses display names (with a detokenize pass if the model leaksp0intotext). Attribution is the snowflake onsubject_id, not the name in the sentence — renames add aliases; they do not move rows. - Anchoring invariant — every fact has exactly one owner (a user or the guild). Links between people/entities are additive.
- Truth maintenance — contradictions invalidate (bitemporal
valid_until) or supersede (refinement chain); nothing auto-deletes. Citations and related-user links survive supersede. Full audit history per fact. - Quality gates — refusals, LLM meta-talk, raw quotes (≥0.88 similarity), questions, snowflakes in text, ephemeral media shares, and low-confidence claims are rejected by pure, unit-tested gates. Registered bots are never subjects and are stripped from mention links.
- Identity ladder — usernames, display names, and saved real names resolve through a source-ranked alias index. Ambiguity never guesses.
- Profile digests — a paragraph summary regenerates after
extraction.auto_consolidate_after_addsnew facts (default 5; not on a timer), stamped with the library clock.
Query shapes (all zero-LLM by default)
| Shape | Example | API |
|---|---|---|
| Profile | "what do you know about X" | recall(subject_ids=(x,)) |
| Cross-linked | "did X call Y a hacker?" | facts touching both via link intersect |
| Relationship | "what does X think about Y" | graph.between(x, y) |
| Entity stance | "who likes movies?" | graph.entity_stances("movies") |
| Hop discovery | "shared connections of X" | graph.neighbors(x, depth=2) |
The consumer surface
memory.observe(event) # → ObserveReceipt (never raises operational errors)
memory.observe_many(events) # bulk backfill
memory.flush(guild_id=...) # force-extract pending batches now
memory.register_bot_id(bot_user_id) # never a memory subject; stripped from mention links
memory.prompt_context(...) # → PromptContext (injection block + citations)
memory.recall(RecallQuery(...)) # explicit query model
memory.facts.remember/update/forget/reinforce/history/list_for_subject/search
memory.identity.resolve/register_alias/handle_member_rename/aliases_of
memory.graph.between/entity_stances/neighbors/relations_of/similar_users
memory.admin.set_opt_out/purge_user/export_guild/get_opt_out
memory.ops.run_pending/retry_dead_letters/meter_snapshot/health
memory.events.subscribe(BatchCompleted, handler) # typed hook events
memory.classify_command(text) # "remember that…" / "forget…" intent detection
memory.regenerate_summaries(guild_id) # force profile digests (else every N new facts)
memory.stats(guild_id) # GuildStats snapshot
Full contract with signatures and semantics: docs/API.md.
Design: docs/PLAN.md · Roadmap: docs/ROADMAP.md.
discord.py integration
# pip install icelake[discord]
from discord.ext import commands
from icelake import MemoryConfig
from icelake.integrations import setup_discord_memory
config = MemoryConfig(
storage="sqlite:///bot-memory.db",
llm="openai://$KEY@openrouter.ai/api/v1?model=google/gemini-3.7-flash",
)
class MyBot(commands.Bot):
async def setup_hook(self) -> None:
memory, helpers = await setup_discord_memory(self, config)
self.memory = memory
# helpers.me / helpers.remember / helpers.forget_me — bind to your own slash commands
The integration wires on_message → observe, on_member_update → alias refresh, and
on_ready → start + register_bot_id. The returned MemoryCog is a helper with
me / remember / forget_me methods you bind to slash commands in your bot — it is
not a commands.Cog subclass. For a full /memory slash group, see
examples/omni_style_bot.py.
Configuration
Providers are URL strings; nested typed configs also accepted:
MemoryConfig(
storage="sqlite:///memory.db", # or mongodb://… ([mongo] extra)
llm="openai://$KEY@openrouter.ai/api/v1?model=…", # OpenAI-compatible endpoints
embeddings="hashing", # free default (see below)
# embeddings="local", # sentence-transformers extra
# embeddings="openai://$KEY@openrouter.ai/api/v1?model=openai/text-embedding-3-small",
# embeddings="openai://$KEY@api.openai.com/v1?model=text-embedding-3-small",
batching={"batch_size_messages": 10, "max_age_seconds": 300},
extraction={"auto_consolidate_after_adds": 5}, # 0 disables profile digests
budgets={"guild_daily_prompt_tokens": 200_000}, # graceful degradation ladder
privacy={"store_raw_messages": True},
workers={"enabled": True, "count": 2},
)
LLM URL query knobs that matter in production: model, temperature=none (omit sampling
on reasoning endpoints), reasoning=low, max_tokens, max_tokens_key=max_completion_tokens
(Azure), structured_outputs=json_object if the endpoint cannot enforce json_schema.
Capability mismatches raise LlmCapabilityError instead of silently degrading.
postgresql:// is recognized and rejected with a clear error — there is no Postgres adapter
yet (and no [postgres] extra).
Unknown keys raise immediately — typo protection by construction.
Embeddings (embeddings=)
| Provider | Spec | Best for |
|---|---|---|
| Hashing (default) | "hashing" |
Tests, zero-dependency demos, deterministic CI |
| Hosted | "openai://$KEY@openrouter.ai/api/v1?model=openai/text-embedding-3-small" |
Production bots already on OpenRouter/OpenAI |
| Local | "local" |
Air-gapped or no embedding API cost (pip install icelake[local-embeddings]) |
Embeddings power semantic recall, reconcile collision detection (paraphrase → reinforce
instead of duplicate ADD), and consolidation sanity checks. Cosine similarity is compared against
extraction.reconcile_collision_threshold (default 0.85).
Hashing embedder limitations
The default hashing embedder is a signed feature-hash over word/char n-grams — not a neural model. It is fast, free, and reproducible, but:
- Paraphrases do not cluster. "Loves coding in Go" and "Enjoys programming in Go" often score below the reconcile threshold, so the pipeline treats them as unrelated facts and you can end up with many near-duplicate memories per user.
- Recall is lexical-ish. Vector search channels rank by token overlap more than meaning; semantic recall quality is noticeably weaker than with a real embedding model.
- Reinforcement depends on collisions. Ingest reinforce/update/noop only triggers semantic collision when cosine similarity clears the threshold; hashing misses most real-world re-statements.
Use hosted (OpenRouter/OpenAI) or local embeddings for any deployment where users repeat
the same preference in different words — including the omni-style example, which sets
embeddings=EMBEDDINGS_URL accordingly. Switching embedders invalidates existing vectors; re-embed
or start fresh on dev databases when changing provider.
Deployment topologies
| Topology | Config |
|---|---|
| Single process (small bots) | defaults — workers run as background tasks |
| Split bot + worker | bot: workers={"enabled": False}; worker process: same storage, call await memory.ops.run_pending() in a loop |
| Cron-style | workers disabled; invoke ops.run_pending from your scheduler |
| Multi-process scale-out | any number of processes share one database — keyed leases make workers cooperative |
Extending (ports)
Every dependency is a Protocol you can replace at construction:
memory = DiscordMemory(
config,
store=MyPostgresStore(), # implements MemoryStore (+ optional .queue/.vectors)
llm=MyLLM(), # implements ChatLLM (OpenAI-compatible shape)
embedder=MyEmbedder(), # implements Embedder
clock=FakeClock(...), # deterministic time in tests
)
New backends must pass the executable conformance suite
(tests/integration/test_store_conformance.py) — the port contract is literally a test.
Development
uv sync --group dev
uv run pytest tests/ -q --cov=icelake # ≥90% coverage enforced
uv run ruff check src tests && uv run ruff format --check src tests
uv run mypy # strict mode
Status & limitations (v0.1)
- Storage backends shipped: SQLite (default), MongoDB (
[mongo]extra), and in-memory (tests). A Postgres/pgvector adapter is planned —postgresql://fails loudly today. - Default hashing embeddings are not suitable for production dedup/recall — see Embeddings above.
- Invalid extraction JSON is repaired once, then dead-lettered (not silently stored as
empty). Re-drive with
ops.retry_dead_letters. - Caps and TTL prune weakest-first (manual/CORE last). Budgets meter per-process; cross-process budget accounting needs store-backed counters.
- Server-scope ("community") batches read the recent-message window; watermarking across restarts is best-effort.
similar_usersuses capped Jaccard over entity adjacency (no Louvain/PPR by design).
See docs/ROADMAP.md for sequenced next work and
docs/PLAN.md for design rationale.
License
MIT
Metadata
Release files for icelake 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| icelake-0.1.0.tar.gz | 424.1 kB | Without provenance | Details for icelake-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| icelake-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for icelake-0.1.0-py3-none-any.whl |
Total release size: 589.3 kB
Release files / icelake-0.1.0.tar.gz
| Download URL | icelake-0.1.0.tar.gz |
|---|---|
| Size | 424.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ec8e3135fbc6a7bdc2efa866bc5835e228a56552610df7988dee8eb9d73a0570
|
|
BLAKE2b-256 checksum How to use checksums |
a50344f7200ef2eeae093e8cf0a3a37ccf9164740fdc2dd30c4a148b73590b04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / icelake-0.1.0-py3-none-any.whl
| Download URL | icelake-0.1.0-py3-none-any.whl |
|---|---|
| Size | 165.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d341341eea3a5e46e47799c9e068ccec036f314b900bc467ac90b8129f9ba56c
|
|
BLAKE2b-256 checksum How to use checksums |
9175a42f70c76252136a0cb4782de6f31760bb8d35a4345ef799600e5d4da155
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for icelake 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.