Memory & state

Memory, progress, and rules auto-persist between executions in <program-dir>/.synsema/state/<name>.db (gitignore .synsema/). remember() in one run is found by recall() in the next.

-- Doc example: agent memory, progress, and owner rules (persist to SQLite).
intent: "doc example: memory, progress, rules"

remember("learning", "demo note from run", ["demo"])
print("recalled → " + text((recall("learning", ["demo"])[0])["content"]))

test "remember then recall — newest first ([0] is the most recent)"
    remember("learning", "API is slow on Mondays", ["api"])
    let notes be recall("learning", ["api"])
    assert_eq((notes[0])["content"], "API is slow on Mondays")

test "progress: resume_point returns the step to resume from"
    create_progress("import", ["ingest", "validate", "load"])
    start_step("import", "ingest")
    complete_step("import", "ingest", "100 rows")
    assert_eq(resume_point("import"), "validate")

test "owner rules: a numeric must-rule flags a violation"
    add_rule("max_discount", "must", "discount <= 0.20", "pricing")
    assert(length(check_rules("pricing", {"discount": 0.25})) > 0)

Persistent memory

remember("learning", "API slow on Mondays", ["api", "performance"])
let notes be recall("learning", ["api"])        -- newest first ([0] = most recent)
let hits  be recall(nothing, nothing, "Monday") -- free-text search (skip args with nothing)
forget_memory(entry_id)

A recall entry is a map with id, category, content, source, tags.

Categories are a fixed English set: preference, rule, learning, decision, context. Any other string (e.g. "preferencia") raises an error. Multi-tag is OR by default; pass mode = "all" for AND.

Progress (crash-resumable)

create_progress("import", ["ingest", "validate", "load"])
start_step("import", "ingest")
complete_step("import", "ingest", "100 rows")     -- or fail_step(...)
let where be resume_point("import")               -- "validate" — where to resume after a restart

Owner rules

add_rule("max_discount", "must", "discount <= 0.20", "pricing")
let violations be check_rules("pricing", {"discount": 0.25})   -- non-empty → violated

Levels: must (hard block), should (warning), avoid / prefer (preferences). Numeric conditions are evaluated against the context map.

Serve state (per-process, in-memory)

Under serve, state_* builtins (e.g. state_incr("visits")) share in-memory state across requests — see HTTP server. (They're a serve feature, not available in plain run.) For durable state, use the memory/progress builtins above or a database.