# lemmalog

Adopt this skill: https://proskills.md/skills/other/jordyzomer-lemmalog-skills-lemmalog

Page: https://proskills.md/skills/other/jordyzomer-lemmalog-skills-lemmalog
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/lemmalog/SKILL.md
size: 8050
upstream: https://github.com/jordyzomer/lemmalog/blob/main/skills/lemmalog/SKILL.md

````text
---
name: lemmalog
description: >-
  Externalize working memory and logical state into the lemmalog Datalog
  engine (MCP). Use for ANY multi-step task where state should outlive one
  context window or span agents: long investigations, debugging sessions,
  audits, multi-agent searches, systematic explorations, planning with many
  interdependent constraints, anything needing provenance for its
  conclusions. Trigger when lemmalog_ MCP tools are available and the task
  involves accumulating verified facts, tracking hypotheses or status over
  time, or repeatedly re-deriving the same relationships.
---

# 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):

```text
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.

## State that changes

Values, quantities, and sets evolve — assert them so the engine can
maintain them (these conventions are what the update policy and the
aggregates need):

- **Update by re-asserting the same relation.** When a value changes,
  assert the new value under the SAME relation name: the policy
  supersedes the old fact automatically. Never invent a synonym
  relation for the new value (`uses` → `switched_to`) — that leaves
  both values open, and every current-state query gets flaky. If you
  need the history, the superseded fact is still queryable by its
  validity interval.
- **Bare numbers are integers.** `launch --monthly_cost--> 120` (never
  `$120` or `120 dollars`) — digit-only objects feed `sum`/`count`
  aggregates and `<`/`>=` comparisons. Mixed forms are opaque symbols.
- **Bare dates order correctly.** `moved_on` with `YYYY-MM-DD` (or
  `YYYY-MM`) objects; derive orderings with a rule
  (`earlier(A, B) :- on(A, D1), on(B, D2), D1 < D2`) rather than
  judging from prose.
- **Evolving sets: one fact per item, plus lifecycle verbs.** Track a
  watchlist/checklist as `added(X)` per item and `watched(X)`/`done(X)`
  when consumed; current membership is then a rule —
  `pendi
````

## File: README.md
upstream: https://github.com/jordyzomer/lemmalog/blob/main/README.md

````text
# Lemmalog

A Datalog engine for LLM agent memory. This repo contains the engine
(Rust crate, MCP server, REPL, agent skill) plus the design document
([`datalog-context-engine-design.md`](datalog-context-engine-design.md),
with an honest status log of what shipped).

The thesis: **an agent's memory should be a deductive database** — the
agent builds a *verifiable model of what it knows* and mechanically
reasons over how that knowledge changes, rather than "remembering
better" than a vector store. Base facts
are asserted at the ingestion boundary (LLM extraction); rules derive
closures, temporal projections, contradiction candidates, and relevance
diffusion; every fact carries provenance back to its source episodes; and
each conversation turn updates derived views incrementally instead of
re-deriving them (or worse, re-reasoning them in-context).

## What's implemented

| Design element | Status |
|---|---|
| Runtime-parsed, stratified Datalog (interpreter, not proc-macro) | ✅ |
| Negation-as-absence with negative-cycle rejection | ✅ |
| Seminaive fixpoint with per-epoch delta maintenance | ✅ |
| Bi-temporal facts via `valid_from`/`valid_to`/`asserted_at` columns + `now()` | ✅ |
| Semiring annotations: confidence (product t-norm) × provenance (set union) | ✅ |
| Annotation merge on re-derivation (max conf, union prov, deduped supports) | ✅ |
| `why()` proof trees with cycle protection | ✅ |
| Additive arithmetic in comparisons (`D = Dm + 1`) with linear solving | ✅ |
| Scoped negative deltas: retraction recomputes only transitive dependents | ✅ |
| `ask()` — read-only datalog query surface for agents | ✅ |
| Magic-sets demand evaluation (`ask_deep`): point queries without full fixpoint | ✅ |
| Per-position secondary indexes; row-id lookups; WAM-style trail backtracking | ✅ |
| Epoch change-log: `changes_from/since` + "new in memory" context section | ✅ |
| Hybrid retrieval (`context_for_query`): BM25 + entity/graph boosting, budget-aware | ✅ |
| Extraction boundary: `Extractor` trait, memoized `MockExtractor` + `LlmExtractor` | ✅ |
| Deterministic update policy: ADD / UPDATE / NOOP / escalate | ✅ |
| Positional `ContextAssembler` (distilled top, verbatim provenance bottom, budget) | ✅ |
| `AgentMemory` facade: observe → policy → maintain → ask/ask_deep/context/why | ✅ |
| Persistence: snapshot save/load (episodes + EDB facts + rules; derived rebuilt) | ✅ |
| Semantic side index: `Embedder` trait, `HashEmbedder`, `seed_mentions` + `near` diffusion | ✅ |
| DRed-lite scoped recompute: supersession rebuilds only what actually changed | ✅ |
| Synthetic eval harness (`scenario::run_eval`): accuracy/token/latency vs. ground truth | ✅ |
| Aggregation: `count`/`min`/`max`/`sum` head args with group-by fold + value-change propagation | ✅ |
| Entity resolution: star-shaped aliasing, directional canonical views, conflict escalation | ✅ |
| MCP server (`--features mcp`): the engine as tools for Claude Code / Kimi CLI | ✅ |
| Rule registry: versioned batches, agent install/uninstall, backfill on change | ✅ |
| Hypotheticals: `what_if` lookahead with byte-identical store restore | ✅ |
| Streaming change feed: `Added`/`Retracted`/`Cleared` events for projections | ✅ |
| Indexed read paths: `query`/`ask` select buckets (point lookups ~100µs at 4M facts) | ✅ |
| Differential testing: 450 random programs vs a naive fixpoint oracle + parser fuzzing | ✅ |
| REPL: `cargo run --bin lemmalog` (rule / + / ? / ?? / why / run / dump / batches) | ✅ |
| Leapfrog triejoins (worst-case-optimal joins), DBSP streaming deltas | 🚧 future phases |

## Entity resolution (canonicalization)

The LLM proposes star-shaped `alias(Local, Canonical)` edges; Datalog
derives the closure; canonical views project facts read-side only
(`src/canonical.rs`):

```prolog
alias(Acme_Corp, Acme).                       % LLM-proposed, confidence-tagged
same_as(X, Y) :- alias(X, Y).                 % symmetric-transitive closure
same_as(X, Z) :- same_as(X, Y), same_as(Y, Z).
maps_to(X, X) :- entity(X), !aliased(X).      % directional projection:
maps_to(L, C) :- alias(L, C).                 %  exactly one canonical spelling
current_canon(S, R, O) :- current(S, R, O), maps_to(S, S2), maps_to(O, O2).
```

Safety properties (all tested): topology violations — a local with two
canonicals, or a name both local and canonical — derive `alias_conflict`
facts instead of merging identities; confidence propagates through the
closure (weak two-hop merges are visibly low-confidence); retracting an
alias edge collapses the closure and every downstream view in the same
epoch. A similarity-gated LLM reconciliation pass
(`canonical::reconcile::reconcile_entities`) offers only
embedding-similar name pairs to the model.

Building this surfaced and fixed two long-lived engine bugs: the scoped
recompute never processed same-stratum dependents (latent stale-fact
bug), fixed by SCC-condensation stratification plus a recompute
fixpoint; and the invalidation pass ran before lower strata were
materialized on first run, fixed by moving invalidation after
evaluation. Both caught by the differential harness.

## The lemmalog skill

`skills/lemmalog/SKILL.md` in this crate is a generic agent skill that makes the engine the task's working memory for
*any* long-running work — investigations, debugging, audits, multi-agent
searches — not just one hardcoded workflow. It encodes the discipline the
live experiments converged on (assert-as-you-verify with anchors and
confidence, rules as experiments, query before re-reasoning, `why` before
trusting, hypothesis lifecycles, decide-from-queries, report-from-the-engine),
the minimal interop schema (`located`, `describes`, `hypothesis`/`status`,
`decision`), the grammar gotchas, and the anti-patterns. Install per CLI:

```sh
# Claude Code (user scope)
mkdir -p ~/.claude/skills && cp -r skills/lemmalog ~/.claude/skills/

# Kimi CLI: copy the same folder into its skills directory
# (e.g. ~/.kimi/skills/lemmalog/ — see its skills docs)
```

Task prompts then stay domain-specific and reference the skill in one line.

## MCP server: use from Claude Code or Kimi CLI

```sh
cargo build --release --features mcp
```

Register the server (stdio JSON-RPC, 12 tools):

```sh
# Claude Code (project or user scope)
claude mcp add lemmalog -- $(pwd)/target/release/lemmalog-mcp

# Kimi CLI
kimi mcp add lemmalog -- $(pwd)/target/release/lemmalog-mcp
```

Or the one-command installer (builds, registers the MCP server with
every supported CLI it finds, installs the skill):

```sh
./scripts/install.sh               # install
./scripts/install.sh --uninstall   # remove registrations + skill
```

Memory persists at `$LEMMALOG_SNAPSHOT` (default `~/.lemmalog/memory.snap`).

Persistence across sessions: set the environment when registering
(both CLIs support `--env KEY=VALUE` on add):

```sh
claude mcp add lemmalog --env LEMMALOG_MCP_PATH=/tmp/lemmalog.snapshot -- \
  $(pwd)/target/release/lemmalog-mcp
```

**Sub-agents that can't reach MCP** (Kimi CLI sub-agents need
`mcp__lemmalog__*` in their agent profile's `tools` list — the bare
`mcp__lemmalog` form matches nothing) and scripts/cron can use the
headless CLI on the same snapshot:

```sh
LEMMALOG_MCP_PATH=/tmp/lemmalog.snapshot lemmalog-cli observe --facts 'S --rel--> O'
LEMMALOG_MCP_PATH=/tmp/lemmalog.snapshot lemmalog-cli query --goal 'current("s", R, O)'
```

Mutations are visible to the MCP server on its next load and vice
versa; the two hold separate in-process copies, so don't write from
both simultaneously (have the parent read while a sub-agent writes, or
route every writer through the CLI).

The intended division of labor: the host model (Claude/Kimi) reads the
conversation and asserts triples via `lemmalog_observe` (line protocol
`S --rel[conf]--> O`); Lemmalog derives closures, temporal views,
canonicalizations and aggregations deterministically. Typical session:

```
lemmalog_observe      {"facts": "Alice --works_at--> Acme\nAlice --manager--> Bob", "ts": 
````
