⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

lemmalog

jordyzomer@jordyzomer⭐ 347 stars· last commit 1mo ago· 1 open issues

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 347 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

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, 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 elementStatus
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):

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:

# 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

cargo build --release --features mcp

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

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

./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):

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:

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": 

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/lemmalog/SKILL.md7.9 KBupstream ↗
    ---
    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
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/jordyzomer-lemmalog-skills-lemmalog.md

// REPO STATS

347 stars
1 open issues
Last commit: 1mo ago