SDK

# 1. Connect
from korely_memory import Korely
korely = Korely(api_key="kor_live_...")

# 2. Remember (typed facts + bi-temporal built-in)
korely.add("User lives in Lisbon", user_id="dana")

# 3. The contradiction resolves itself: the new fact
#    invalidates the old one, never deletes it
korely.add("User just moved to Berlin", user_id="dana")

# 4. Recall once extraction has run (a few seconds after each add):
#    the active facts, assembled into a prompt-ready block
ctx = korely.get_context(query="where does the user live", user_id="dana")
print(ctx.context)
# A note for the model that reads the block, then:
# ## Known facts
# - The user lives_in Berlin (since 2026-06-11)
#
# ## Relevant memories
# ...
# The superseded Lisbon fact is not among the known facts.

// 1. Connect
import { Korely } from "korely-memory";
const korely = new Korely({ apiKey: "kor_live_..." });

// 2. Remember (typed facts + bi-temporal built-in)
await korely.add("User lives in Lisbon", { user_id: "dana" });

// 3. The contradiction resolves itself: the new fact
//    invalidates the old one, never deletes it
await korely.add("User just moved to Berlin", { user_id: "dana" });

// 4. Recall once extraction has run (a few seconds after each add):
//    the active facts, assembled into a prompt-ready block
const ctx = await korely.getContext({ query: "where does the user live", user_id: "dana" });
console.log(ctx.context);
// A note for the model that reads the block, then:
// ## Known facts
// - The user lives_in Berlin (since 2026-06-11)
//
// ## Relevant memories
// ...
// The superseded Lisbon fact is not among the known facts.

from korely_memory import Korely

korely = Korely(api_key="kor_live_...")

# Or read the key from the environment (KORELY_API_KEY)
korely = Korely()

import { Korely } from "korely-memory";

const korely = new Korely({ apiKey: "kor_live_..." });

// Or read the key from the environment (KORELY_API_KEY):
// const korely = new Korely();

memory = korely.add(
    "Northwind Hosting costs 50 euro per month since the June upgrade.",
    agent_id="infra-bot",
    user_id="customer-4812",
    metadata={"source": "slack"},
)

print(memory.id)       # mem_8f2c1a
print(memory.status)   # processing: facts are extracted after the call returns
print(memory.facts)    # []

# A few seconds later
facts = korely.get_facts(entity="Northwind Hosting", user_id="customer-4812")
print(facts[0].subject, facts[0].predicate, facts[0].object)
# Northwind Hosting costs 50 euro per month

const memory = await korely.add(
  "Northwind Hosting costs 50 euro per month since the June upgrade.",
  {
    agent_id: "infra-bot",
    user_id: "customer-4812",
    metadata: { source: "slack" },
  },
);

console.log(memory.id);      // mem_8f2c1a
console.log(memory.status);  // processing: facts are extracted after the call returns
console.log(memory.facts);   // []

// A few seconds later
const facts = await korely.getFacts({ entity: "Northwind Hosting", user_id: "customer-4812" });
console.log(facts[0].subject, facts[0].predicate, facts[0].object);
// Northwind Hosting costs 50 euro per month

# The log of a work session, saved as what it is
korely.add(
    "Session: moved the billing service to Postgres 16, tests pass, rollback script in ops/.",
    user_id="dev-team",
    kind="session",
)

# A decision, saved as a note (the default kind)
korely.add("We bill in euro only, agreed with finance.", user_id="dev-team")

# Reads that leave the work sessions out
ctx = korely.get_context("how do we bill customers", user_id="dev-team", exclude_sessions=True)
hits = korely.search("billing currency", user_id="dev-team", exclude_sessions=True)
facts = korely.get_facts(user_id="dev-team", exclude_sessions=True)

# Each memory says which kind it is
page = korely.get_all(user_id="dev-team")
print([m.kind for m in page.memories])  # ['note', 'session']

# A batch item takes kind too
korely.batch([
    {"content": "Session: added retries to the invoice sender.", "user_id": "dev-team", "kind": "session"},
    {"content": "Invoices go out on the first working day.", "user_id": "dev-team"},
])

// The log of a work session, saved as what it is
await korely.add(
  "Session: moved the billing service to Postgres 16, tests pass, rollback script in ops/.",
  { user_id: "dev-team", kind: "session" },
);

// A decision, saved as a note (the default kind)
await korely.add("We bill in euro only, agreed with finance.", { user_id: "dev-team" });

// Reads that leave the work sessions out
const ctx = await korely.getContext({ query: "how do we bill customers", user_id: "dev-team", exclude_sessions: true });
const hits = await korely.search("billing currency", { user_id: "dev-team", exclude_sessions: true });
const facts = await korely.getFacts({ user_id: "dev-team", exclude_sessions: true });

// Each memory says which kind it is
const page = await korely.getAll({ user_id: "dev-team" });
console.log(page.memories.map((m) => m.kind)); // [ 'note', 'session' ]

// A batch item takes kind too
await korely.batch([
  { content: "Session: added retries to the invoice sender.", user_id: "dev-team", kind: "session" },
  { content: "Invoices go out on the first working day.", user_id: "dev-team" },
]);

results = korely.search(
    "northwind pricing",
    user_id="customer-4812",
    limit=5,
)

for hit in results:
    print(hit.id, hit.score, hit.snippet)
    # mem_8f2c1a 0.91 Northwind Hosting costs 50 euro per month...

const results = await korely.search(
  "northwind pricing",
  { user_id: "customer-4812", limit: 5 },
);

for (const hit of results) {
  console.log(hit.id, hit.score, hit.snippet);
  // mem_8f2c1a 0.91 Northwind Hosting costs 50 euro per month...
}

page = korely.get_all(
    user_id="customer-4812",
    limit=50,
    offset=0,
)

print(page.total)  # 218
for memory in page:
    print(memory.id, memory.created_at)
    # mem_8f2c1a 2026-06-07T09:14:00.412345+00:00

const page = await korely.getAll({
  user_id: "customer-4812",
  limit: 50,
  offset: 0,
});

console.log(page.total); // 218
for (const memory of page.memories) {
  console.log(memory.id, memory.created_at);
  // mem_8f2c1a 2026-06-07T09:14:00.412345+00:00
}

memory = korely.get("mem_8f2c1a")

print(memory.content)     # Northwind Hosting costs 50 euro per month...
print(memory.metadata)    # {"source": "slack"}
print(memory.created_at)  # 2026-06-07T09:14:00.412345+00:00

const memory = await korely.get("mem_8f2c1a");

console.log(memory.content);     // Northwind Hosting costs 50 euro per month...
console.log(memory.metadata);    // { source: "slack" }
console.log(memory.created_at);  // 2026-06-07T09:14:00.412345+00:00

current = korely.get("mem_8f2c1a")
memory = korely.update(
    "mem_8f2c1a",
    content="Northwind Hosting costs 55 euro per month after the storage add-on.",
    # the exact value the API returned, never one typed by hand
    expected_updated_at=current.updated_at or current.created_at,
)

print(memory.status)   # processing
print(memory.facts)    # [], the new facts arrive a few seconds later

# Read them afterwards (newest first)
facts = korely.get_facts(entity="Northwind Hosting", user_id="customer-4812")
print(facts[0].object)  # 55 euro per month

const current = await korely.get("mem_8f2c1a");
const memory = await korely.update(
  "mem_8f2c1a",
  {
    content: "Northwind Hosting costs 55 euro per month after the storage add-on.",
    // the exact value the API returned, never one typed by hand
    expected_updated_at: current.updated_at ?? current.created_at,
  },
);

console.log(memory.status);  // processing
console.log(memory.facts);   // [], the new facts arrive a few seconds later

// Read them afterwards (newest first)
const facts = await korely.getFacts({ entity: "Northwind Hosting", user_id: "customer-4812" });
console.log(facts[0].object);  // 55 euro per month

receipt = korely.delete("mem_8f2c1a")

print(receipt.status)             # forgotten
print(receipt.facts_invalidated)  # 1
print(receipt.audit_id)           # aud_3d0f

const receipt = await korely.delete("mem_8f2c1a");

console.log(receipt.status);             // forgotten
console.log(receipt.facts_invalidated);  // 1
console.log(receipt.audit_id);           // aud_3d0f

receipt = korely.delete_all(user_id="customer-4812")

print(receipt.memories_deleted)    # 218
print(receipt.facts_deleted)       # 64
print(receipt.audit_id)            # aud_91xb

const receipt = await korely.deleteAll({ user_id: "customer-4812" });

console.log(receipt.memories_deleted);    // 218
console.log(receipt.facts_deleted);       // 64
console.log(receipt.audit_id);            // aud_91xb

declared = korely.declare_name("Maria Rossi", user_id="maria")
print(declared.user_id, declared.name)   # maria Maria Rossi
print(declared.since)                    # 2026-10-18T21:04:11.412345Z

# The facts about "Maria Rossi" now come back under maria
facts = korely.get_facts(user_id="maria", subject="maria")

const declared = await korely.declareName("Maria Rossi", { user_id: "maria" });
console.log(declared.user_id, declared.name);   // maria Maria Rossi
console.log(declared.since);                    // 2026-10-18T21:04:11.412345Z

// The facts about "Maria Rossi" now come back under maria
const facts = await korely.getFacts({ user_id: "maria", subject: "maria" });

# Current state: only active facts
facts = korely.get_facts(entity="Northwind Hosting")
print(facts[0].object)      # 50 euro per month
print(facts[0].invalid_at)  # None, active

# Point-in-time: what was true on June 1?
facts = korely.get_facts(entity="Northwind Hosting", as_of="2026-06-01")
print(facts[0].object)      # 40 euro per month
print(facts[0].invalid_at)  # 2026-06-07T09:14:00+00:00, superseded since

# Full history chain, superseded facts included
facts = korely.get_facts(
    entity="Northwind Hosting",
    include_invalidated=True,
)

# What the store knew on June 1: a change told later is not in it
facts = korely.get_facts(entity="Northwind Hosting", known_as_of="2026-06-01")
print(facts[0].object)           # 40 euro per month
print(facts[0].closed_known_at)  # None, its end was learned on June 7

// Current state: only active facts
let facts = await korely.getFacts({ entity: "Northwind Hosting" });
console.log(facts[0].object);      // 50 euro per month
console.log(facts[0].invalid_at);  // null, active

// Point-in-time: what was true on June 1?
facts = await korely.getFacts({ entity: "Northwind Hosting", as_of: "2026-06-01" });
console.log(facts[0].object);      // 40 euro per month
console.log(facts[0].invalid_at);  // 2026-06-07T09:14:00+00:00, superseded since

// Full history chain, superseded facts included
facts = await korely.getFacts({
  entity: "Northwind Hosting",
  include_invalidated: true,
});

// What the store knew on June 1: a change told later is not in it
facts = await korely.getFacts({ entity: "Northwind Hosting", known_as_of: "2026-06-01" });
console.log(facts[0].object);           // 40 euro per month
console.log(facts[0].closed_known_at);  // null, its end was learned on June 7

ctx = korely.get_context(
    query="plan infra budget",
    user_id="customer-4812",
    token_budget=800,
)

print(ctx.tokens)   # 642
print(ctx.sources)  # ["fct_b91e", "mem_8f2c1a"]

messages = [
    {"role": "system", "content": f"You are a helpful assistant.\n\n{ctx.context}"},
    {"role": "user", "content": user_message},
]

const ctx = await korely.getContext({
  query: "plan infra budget",
  user_id: "customer-4812",
  token_budget: 800,
});

console.log(ctx.tokens);   // 642
console.log(ctx.sources);  // ["fct_b91e", "mem_8f2c1a"]

const messages = [
  { role: "system", content: `You are a helpful assistant.\n\n${ctx.context}` },
  { role: "user", content: userMessage },
];

job = korely.batch([
    {"content": "Prefers async standups over meetings.", "user_id": "customer-0001"},
    {"content": "Renewal date moved to October 1st.", "user_id": "customer-0002"},
])

print(job.status)   # pending (then processing, then completed or failed)

job = korely.batch_status(job.id)
print(job.status)   # completed
print(job.imported) # 2

let job = await korely.batch([
  { content: "Prefers async standups over meetings.", user_id: "customer-0001" },
  { content: "Renewal date moved to October 1st.", user_id: "customer-0002" },
]);

console.log(job.status);   // pending

job = await korely.batchStatus(job.id);
console.log(job.status);   // completed
console.log(job.imported); // 2

fact = korely.add_fact_triple(
    "Marco", "works_at", "Acme GmbH",
    user_id="customer-4812",
    subject_type="person",
    valid_from="2026-06-01",
)

print(fact.invalidated)  # ids of any facts this one superseded

const fact = await korely.addFactTriple(
  "Marco", "works_at", "Acme GmbH",
  {
    user_id: "customer-4812",
    subject_type: "person",
    valid_from: "2026-06-01",
  },
);

console.log(fact.invalidated);  // ids of any facts this one superseded

profile = korely.get_profile(user_id="customer-4812")
print(profile.total)              # 7
print(list(profile.by_family))    # ["places", "work", "preferences"]

# The profile as it stood on March 1st
past = korely.get_profile(user_id="customer-4812", as_of="2026-03-01")

# The profile as the store knew it on March 1st
known = korely.get_profile(user_id="customer-4812", known_as_of="2026-03-01")

const profile = await korely.getProfile({ user_id: "customer-4812" });
console.log(profile.total);                 // 7
console.log(Object.keys(profile.by_family)); // ["places", "work", "preferences"]

// The profile as it stood on March 1st
const past = await korely.getProfile({ user_id: "customer-4812", as_of: "2026-03-01" });

// The profile as the store knew it on March 1st
const known = await korely.getProfile({ user_id: "customer-4812", known_as_of: "2026-03-01" });

h = korely.history("mem_8f2c1a")
for event in h.events:
    print(event.event, event.at)   # created ... / fact_extracted ...

const h = await korely.history("mem_8f2c1a");
for (const event of h.events) {
  console.log(event.event, event.at);   // created ... / fact_extracted ...
}

page = korely.users()
print(page.total)                 # 1
for u in page:
    print(u.user_id, u.memories, u.facts)

const page = await korely.users();
console.log(page.total);                // 1
for (const u of page.users) {
  console.log(u.user_id, u.memories, u.facts);
}

fact = korely.correct_fact("fct_a1", object="Beacon Labs")
print(fact.object, fact.invalid_at)   # Beacon Labs None

const fact = await korely.correctFact("fct_a1", { object: "Beacon Labs" });
console.log(fact.object, fact.invalid_at);   // Beacon Labs null

receipt = korely.forget_fact("fct_9c1e", at="2026-06-30")
print(receipt["status"])   # forgotten

const receipt = await korely.forgetFact("fct_9c1e", { at: "2026-06-30" });
console.log(receipt.status);   // forgotten

page = korely.list_agents()
print(page.used, "of", page.cap)   # 2 of 2
for a in page:
    print(a.agent_id, a.memories, a.facts)

const page = await korely.listAgents();
console.log(page.used, "of", page.cap);   // 2 of 2
for (const a of page.agents) {
  console.log(a.agent_id, a.memories, a.facts);
}

receipt = korely.delete_agent("staging-bot")
print(receipt.memories_deleted, receipt.facts_deleted, receipt.audit_id)

const receipt = await korely.deleteAgent("staging-bot");
console.log(receipt.memories_deleted, receipt.facts_deleted, receipt.audit_id);

result = korely.events(user_id="customer-4812")
print(result["processing"])            # 0
for e in result["events"]:
    print(e["memory_id"], e["status"])  # mem_8f2c1a ready

const result = await korely.events({ user_id: "customer-4812" });
console.log(result.processing);           // 0
for (const e of result.events) {
  console.log(e.memory_id, e.status);     // mem_8f2c1a ready
}

"""
Support bot with persistent per-customer memory.
Uses korely-memory for context recall and fact storage.
"""
import os
from google import genai
from korely_memory import Korely, APIError

korely = Korely(api_key=os.environ["KORELY_API_KEY"])
client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])

AGENT = "support-bot"

def chat(user_id: str, user_message: str) -> str:
    # 1. Assemble memory context for this user + query
    ctx = korely.get_context(
        query=user_message,
        agent_id=AGENT,
        user_id=user_id,
        token_budget=600,
    )

    system = (
        "You are a concise support assistant. "
        "Use the memory context below to personalise your reply.\n\n"
        + ctx.context
    )

    # 2. Call the LLM
    reply = client.models.generate_content(
        model="gemini-3.6-flash",
        contents=system + "\n\nUser: " + user_message,
    ).text

    # 3. Persist what the user said (extracts facts, detects contradictions)
    try:
        korely.add(
            user_message,
            agent_id=AGENT,
            user_id=user_id,
            metadata={"turn": "user"},
        )
    except APIError as err:
        if err.code != "quota_exceeded":
            raise
        pass   # over the write quota, log and continue, the reply was already generated

    return reply


# --- run a two-turn session ---
uid = "customer-4812"

print(chat(uid, "Hi, I am on the Developer plan and I prefer async updates."))
# context is empty on first turn, the bot greets + confirms

print(chat(uid, "What plan am I on again?"))
# second turn: context block contains the plan + preference facts from turn 1
# → bot answers correctly without the user repeating themselves

/**
 * Support bot with persistent per-customer memory.
 * Uses korely-memory for context recall and fact storage.
 */
import { Korely, APIError } from "korely-memory";
import { GoogleGenAI } from "@google/genai";

const korely = new Korely({ apiKey: process.env.KORELY_API_KEY! });
const ai = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY! });

const AGENT = "support-bot";

async function chat(userId: string, userMessage: string): Promise<string> {
  // 1. Assemble memory context for this user + query
  const ctx = await korely.getContext({
    query: userMessage,
    agent_id: AGENT,
    user_id: userId,
    token_budget: 600,
  });

  const systemPrompt =
    "You are a concise support assistant. " +
    "Use the memory context below to personalise your reply.\n\n" +
    ctx.context;

  // 2. Call the LLM
  const result = await ai.models.generateContent({
    model: "gemini-3.6-flash",
    contents: systemPrompt + "\n\nUser: " + userMessage,
  });
  const reply = result.text ?? "";

  // 3. Persist what the user said (extracts facts, detects contradictions)
  try {
    await korely.add(userMessage, {
      agent_id: AGENT,
      user_id: userId,
      metadata: { turn: "user" },
    });
  } catch (err) {
    if (!(err instanceof APIError) || err.code !== "quota_exceeded") throw err;
    // over the write quota, log and continue, the reply was already generated
  }

  return reply;
}

// --- run a two-turn session ---
const uid = "customer-4812";

console.log(await chat(uid, "Hi, I am on the Developer plan and I prefer async updates."));
// context is empty on first turn, the bot greets + confirms

console.log(await chat(uid, "What plan am I on again?"));
// second turn: context block contains the plan + preference facts from turn 1
// → bot answers correctly without the user repeating themselves

# Write: scoped to this customer
korely.add(
    "Asked to be contacted on Slack, not email.",
    agent_id="support-bot",
    user_id="customer-4812",
    run_id="session-2026-06-11",
)

# Read: only this customer's memory comes back
results = korely.search("contact preference", user_id="customer-4812")

// Write: scoped to this customer
await korely.add(
  "Asked to be contacted on Slack, not email.",
  {
    agent_id: "support-bot",
    user_id: "customer-4812",
    run_id: "session-2026-06-11",
  },
);

// Read: only this customer's memory comes back
const results = await korely.search("contact preference", { user_id: "customer-4812" });

from korely_memory import Korely, APIError

korely = Korely(api_key="kor_live_...")

try:
    memory = korely.get("mem_8f2c1a")
except APIError as err:
    if err.code == "invalid_key":
        # 401: check the key, or create a new one in the dashboard
        raise
    elif err.code == "not_found":
        # 404: the memory does not exist, or an end user forgot it
        memory = None
    elif err.code == "quota_exceeded":
        # 429: monthly query quota reached (get() is a read), upgrade or wait for the reset
        memory = None
    else:
        raise

import { Korely, APIError } from "korely-memory";

const korely = new Korely({ apiKey: "kor_live_..." });

let memory;
try {
  memory = await korely.get("mem_8f2c1a");
} catch (err) {
  if (!(err instanceof APIError)) throw err;
  if (err.code === "invalid_key") {
    // 401: check the key, or create a new one in the dashboard
    throw err;
  } else if (err.code === "not_found") {
    // 404: the memory does not exist, or an end user forgot it
    memory = null;
  } else if (err.code === "quota_exceeded") {
    // 429: monthly query quota reached (get() is a read), upgrade or wait for the reset
    memory = null;
  } else {
    throw err;
  }
}