Lemmalog

Lemmalog — external working memory

lemmalog is a Datalog engine exposed as MCP tools. It is your working memory: assertions with provenance and confidence, derived consequences computed by rules, hypotheses with lifecycles — persistent across agents and context resets.

The division of labor: the engine owns state and consequence; you own perception and choice; every choice's outcome returns to the engine. A claim that isn't in the engine doesn't exist — nothing durable lives in your context.

Setup

• The lemmalog_* tools must be registered (see the README of the lemmalog repo). If they are absent, tell the user the one-line registration command and continue without memory — never block the task.
• Persistence across sessions exists if LEMMALOG_MCP_PATH was set at registration; lemmalog_save forces a snapshot. Snapshots carry rule batches too — installed analyses survive restarts under their batch ids.
• No MCP access (sub-agents that don't inherit MCP connections, scripts, cron)? lemmalog-cli works on the SAME snapshot: LEMMALOG_MCP_PATH=... lemmalog-cli observe --facts 'S --rel--> O', plus query/retract/context/why/rules/dump. Mutations are visible to the MCP server on its next load and vice versa — but the two hold separate in-process copies, so don't write from both at once: hand sub-agents the CLI and keep the parent on it too, or have the parent only read while a sub-agent writes.

The discipline

1. Assert as you verify. The moment you confirm something — a call edge, a config value, a decision, a step completed — assert it: S --rel[conf]--> O. Tag read-and-verified facts [1.0] and inferences [0.4]–[0.7]. Do not omit the tag on anything you expect to derive over: the default is 0.9 and confidence is a product down the proof chain, so four hops of "verified" facts land at 0.66 and a deep closure decays to noise. Anchor evidence with located(Entity, "file:line") (or any stable reference) so provenance survives derivation — source references are valid entity tokens as long as they contain no spaces. Never assert what you haven't checked.
2. Install rules when a pattern repeats. If you ask the same shape of question twice, write the Datalog for it: transitive closures, guard tracking, status rollups, count/min/max/sum aggregates. Rules are experiments: one named batch per analysis idea, validated on install (rejections are spec feedback), backfilled against everything already asserted, lemmalog_uninstall when the idea dies.
3. Query before re-reasoning. Multi-hop, transitive, or not-X-reachable questions go through rules and lemmalog_query — never mental closure, and never re-deriving what a prior agent derived. For grounded answering, lemmalog_context retrieves the question-relevant facts plus their verbatim source episodes under a token budget, with an attribution contrast (which subjects hold facts on the topic — a question-mentioned party with zero topic facts is a false-premise signal) and, for current-state questions, the latest value per slot with supersessions as history — use it instead of lemmalog_dump when preparing answers; selection beats dumping.
4. lemmalog_why before trusting any derived fact. The proof tree shows which asserted edges carry it; a chain is only as good as its lowest-confidence edge. Re-verify the weakest edges against their located anchors.
5. Hypotheses have lifecycles. H --hypothesis--> claim, H --status--> proposed|supported|refuted|validated (supersedes), H --evidence--> ref (accumulates). Test counterfactuals with lemmalog_what_if — temporary facts, answered goal, store untouched.
6. Correct by retracting. When you learn an asserted fact was wrong — not changed, wrong — lemmalog_retract it: the response lists every derived conclusion that died with it, so the repair is visible, not silent. (A value that merely changed is re-asserted under the same relation; see "State that changes".) After a context reset or another agent's turn, lemmalog_changes with your last epoch resyncs you without re-reading the store.
7. Reconcile vocabulary, don't enforce it. Name things naturally; when two names mean one thing, local --alias_of[conf]--> canonical via lemmalog_canonicalize. Conflicts surface as alias_conflict facts; they never silently merge.
8. Decide from queries. Derive candidate views — unexplored items, blocked-by-what, what-needs-attention — and choose among them. The queries propose; you dispose (including off-list when judgment says so). Then assert the decision so state stays complete.
9. Report from the engine. Final deliverables render from queries and why trees, not from memory. A conclusion's confidence is the product of its edges (the engine multiplies down the proof chain) — deep derivations need high-confidence inputs to stay believable.

Schema conventions

The only shared vocabulary (everything else: invent precisely, and assert describes(Relation, "one-line meaning") so others discover it):

All asserted through the line protocol (the predicate forms below are descriptions, not assertable syntax):

kernel_func --located--> vm/vm_map.c:3052     % evidence anchor (multi-valued)
works_at --describes--> person is employed at % self-documenting schema
hyp_1 --hypothesis--> claim in plain words    % lifecycle-tracked claim
hyp_1 --status--> proposed                    % supersedes on change:
                                              % proposed|supported|refuted|validated
hyp_1 --evidence--> vm_map.c:3052            % multi-valued: accumulates
decision_7 --decision--> chose scope X because Y

Evidence objects take a bare source reference (space-free) or a punctuation-free phrase; spaces plus punctuation read as leaked prose and are dropped. Symmetric quotes around subjects/objects are stripped ("mean field" lands as mean field) — multi-word values are fine up to 8 words; compress longer prose into a short name or split it.