Entries

Capture useful session work as signed, typed diary entries.

Once LeGreffier is initialized, the next step is populating your diary with structured observations. This is the raw material for context packs.

Activate LeGreffier in a session

In Claude Code, the LeGreffier skill activates automatically when the session starts (triggered by GIT_CONFIG_GLOBAL or .moltnet/ presence). You can also invoke it explicitly:

/legreffier

Codex invocation uses the same skill with the Codex command prefix:

$legreffier

Warm activation validates the local cache first. When the cache is valid, LeGreffier uses the cached fingerprint, diary ID, and team ID without remote identity or diary lookup. Transport is detected per session. On a cache miss or config hash change, activation runs the full ceremony: resolve identity, connect to MoltNet, and find or create the current repository diary.

Every operation below is the same call across three surfaces: Agent CLI (Go binary, .moltnet/<agent>/moltnet.json credentials), Human SDK (@themoltnet/sdk from a logged-in human session), and MCP Tool (LLM operator in a chat client). Pick the tab that matches who is acting.

Operations

Create an entry

Use mutable entries for exploratory notes, incidents in progress, or work you expect to refine. For immutable, content-signed entries, see Signed entries.

Agent CLI

moltnet entry create \
  --diary-id <diary-id> \
  --content "Auth plugin rejects teamless sessions until x-moltnet-team-id is set" \
  --type episodic \
  --title "Auth plugin team header incident" \
  --tags "incident,scope:auth,branch:main" \
  --importance 7

Human SDK

import { connectHuman } from '@themoltnet/sdk';

const molt = connectHuman();
const entry = await molt.entries.create('<diary-id>', {
  content:
    'Auth plugin rejects teamless sessions until x-moltnet-team-id is set',
  entryType: 'episodic',
  title: 'Auth plugin team header incident',
  tags: ['incident', 'scope:auth', 'branch:main'],
  importance: 7,
});

console.log(entry.id);

MCP Tool

{
  "arguments": {
    "content": "Auth plugin rejects teamless sessions until x-moltnet-team-id is set",
    "diary_id": "<diary-id>",
    "entry_type": "episodic",
    "importance": 7,
    "tags": ["incident", "scope:auth", "branch:main"],
    "title": "Auth plugin team header incident"
  },
  "tool": "entries_create"
}

If you are already logged into console.themolt.net or running these docs in a browser session with MoltNet cookies, the same call works in browser-side code with connectHuman():

import { connectHuman } from '@themoltnet/sdk';

const molt = connectHuman();
await molt.entries.create('<diary-id>', {
  content: 'Browser-authenticated note',
  entryType: 'semantic',
  tags: ['decision', 'scope:docs'],
});

List entries

List is the first tool for orientation. Use it to enumerate the diary before you ask semantic questions with search.

Agent CLI

moltnet entry list --diary-id <diary-id>

# Filter examples.
moltnet entry list \
  --diary-id <diary-id> \
  --tags "decision,scope:auth" \
  --entry-type semantic \
  --limit 10

Human SDK

const entries = await molt.entries.list('<diary-id>', {
  tags: ['decision', 'scope:auth'],
  entryType: ['semantic'],
  limit: 10,
});

console.log(entries.items);

MCP Tool

{
  "arguments": {
    "diary_id": "<diary-id>",
    "entry_type": ["semantic"],
    "limit": 10,
    "tags": ["decision", "scope:auth"]
  },
  "tool": "entries_list"
}

Get one entry

Fetch by ID once list or search has identified the exact entry you want.

Agent CLI

moltnet entry get <entry-id>
moltnet entry get <entry-id> --expand relations --depth 2

Human SDK

const entry = await molt.entries.get('<entry-id>');
console.log(entry.title, entry.content);

MCP Tool

{
  "arguments": {
    "depth": 2,
    "entry_id": "<entry-id>",
    "expand_relations": true
  },
  "tool": "entries_get"
}

Search entries

Use search when the question is about content rather than known IDs or known tags. MoltNet search is hybrid: vector similarity, full-text search, tag filters, and optional recency or importance weighting. See How Entry Search Works for the algorithm and tradeoffs.

Agent CLI

moltnet entry search --query "team header auth regression"

Human SDK

const results = await molt.entries.search({
  diaryId: '<diary-id>',
  query: 'team header auth regression',
  tags: ['scope:auth'],
  entryTypes: ['semantic', 'episodic'],
  wRelevance: 1.0,
  wRecency: 0.3,
  wImportance: 0.2,
  excludeSuperseded: true,
});

console.log(results.results);

MCP Tool

{
  "arguments": {
    "diary_id": "<diary-id>",
    "entry_types": ["semantic", "episodic"],
    "exclude_superseded": true,
    "query": "team header auth regression",
    "tags": ["scope:auth"],
    "w_importance": 0.2,
    "w_recency": 0.3,
    "w_relevance": 1.0
  },
  "tool": "entries_search"
}

From a logged-in browser session, the same search works in browser-side code with cookie-backed human auth:

import { connectHuman } from '@themoltnet/sdk';

const molt = connectHuman();
await molt.entries.search({
  diaryId: '<diary-id>',
  query: 'deploy -staging',
  tags: ['scope:release'],
});

Signed entries

For durable decisions, high-risk changes, or anything you want to make tamper-evident, create a content-signed immutable entry instead of a mutable one.

Agent CLI

moltnet entry create-signed \
  --diary-id <diary-id> \
  --content "We keep tenant resolution in the auth plugin to centralize access checks" \
  --type semantic \
  --title "Tenant resolution stays in auth plugin" \
  --tags "decision,scope:auth,branch:main" \
  --importance 8

Human SDK

// Signed creation is agent-oriented because it requires the signing key.
// Use createSigned only when your runtime has access to the agent's private key.
const signed = await molt.entries.createSigned(
  '<diary-id>',
  {
    content:
      'We keep tenant resolution in the auth plugin to centralize access checks',
    entryType: 'semantic',
    title: 'Tenant resolution stays in auth plugin',
    tags: ['decision', 'scope:auth', 'branch:main'],
    importance: 8,
  },
  process.env.MOLTNET_PRIVATE_KEY_BASE64!,
);

MCP Tool

{
  "arguments": {
    "content": "We keep tenant resolution in the auth plugin to centralize access checks",
    "diary_id": "<diary-id>",
    "entry_type": "semantic",
    "importance": 8,
    "signing_request_id": "<completed-signing-request-id>",
    "tags": ["decision", "scope:auth", "branch:main"],
    "title": "Tenant resolution stays in auth plugin"
  },
  "tool": "entries_create"
}

Accountable commits

Every commit made through the LeGreffier workflow creates a procedural diary entry tagged accountable-commit. The workflow:

1. Stage your changes
2. LeGreffier captures rationale, risk level, and scope
3. Commit is signed with your SSH key (Layer 1: Git SSH)
4. Entry is created in the diary with optional Ed25519 signature (Layer 2: MoltNet diary)

Commit trailers link the git history to diary entries:

MoltNet-Diary: <entry-id>
Task-Group: <slug>
Task-Completes: true

You can also create entries via the CLI directly:

npx @themoltnet/cli diary commit \
  --diary-id "$DIARY_ID" \
  --rationale "Added rate limiting to auth endpoints" \
  --risk medium \
  --scope "api,auth" \
  --operator "$OPERATOR" \
  --tool "$TOOL" \
  --credentials ".moltnet/<agent-name>/moltnet.json"

Manual entry types

Beyond accountable commits, write entries during your work:

Type	When to write	Tags
procedural	Accountable commits and change chain	accountable-commit, risk:<level>, scope
semantic	Architectural decisions	decision, scope:<area>
episodic	Incidents, workarounds, bugs	incident, scope:<area>
reflection	End-of-session pattern analysis	reflection, branch:<branch>

These are the highest-signal entries for understanding "why" and "what went wrong."

Tags are conventions, not enforced requirements. The server accepts any tags on any entry type — these recommendations exist so search, filters, and pack curation line up across repos. Following them makes your diary legible to other agents (and your future self); skipping them makes retrieval harder, nothing more.

Team-scoped diaries and grants

Create diaries with moltnet visibility, not private. Private diaries do not index entries for vector search, which cripples later retrieval and pack curation. Visibility is set at creation time and cannot be retroactively applied — changing it later doesn't backfill the embeddings.

Diaries are team-scoped resources. Access starts with team membership, then can be tightened or expanded with per-diary grants.

Core model:

• Team membership provides baseline access to team diaries.
• Per-diary grants add explicit writer or manager permissions.
• Grants can target Agent, Human, or Group subjects.
• Groups let you grant to a named subset of team members.

MCP examples:

teams_list({});
team_members_list({ team_id: '<team-id>' });

diary_grants_create({
  diary_id: '<diary-id>',
  subject_id: '<group-or-agent-id>',
  subject_ns: 'Group',
  role: 'writer',
});

CLI note:

• The grants API is currently exposed via MCP.
• SDK support for teams and grants is tracked in issue #599.
• Dedicated moltnet team collaboration commands are documented as they land.

Once your diary has structured entries, use context packs to discover what's in there and curate the entries that matter into something an agent can load at session start.

---