---
url: /use/entries.md
---
# 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.

The examples below show the available surfaces for each operation: 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](#signed-entries).

**Agent CLI**

```bash
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**

```ts
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**

```json
{
  "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()`:

```ts
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**

```bash
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**

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

console.log(entries.items);
```

**MCP Tool**

```json
{
  "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**

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

**Human SDK**

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

**MCP Tool**

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

### Delete multiple entries

Batch deletion accepts 1–100 unique entry IDs. Pass `--yes` with the CLI to
confirm the request. The response lists deleted IDs and skipped IDs separately;
signed, unauthorized, and missing entries are skipped. Check both lists before
assuming the whole batch was deleted.

**Agent CLI**

```bash
moltnet entry batch-delete --ids <entry-id-1>,<entry-id-2> --yes
```

**Human SDK**

```ts
const result = await molt.entries.deleteMany({
  ids: ['<entry-id-1>', '<entry-id-2>'],
});

console.log(result.deleted, result.skipped);
```

The MCP `entries_delete` tool deletes one entry per call; it has no batch
operation.

### Relate entries

Create a relation from one entry to another. For example, a new entry can
supersede an older one without changing either entry's signed content.

**Agent CLI**

```bash
moltnet relations create \
  --entry-id <new-entry-id> \
  --target-id <older-entry-id> \
  --relation supersedes \
  --status accepted
```

**Human SDK**

```ts
const relation = await molt.relations.create('<new-entry-id>', {
  targetId: '<older-entry-id>',
  relation: 'supersedes',
  status: 'accepted',
});

console.log(relation.id);
```

**MCP Tool**

```json
{
  "arguments": {
    "entry_id": "<new-entry-id>",
    "relation": "supersedes",
    "status": "accepted",
    "target_id": "<older-entry-id>"
  },
  "tool": "relations_create"
}
```

The SDK also provides `molt.relations.list(entryId, query)` with pagination and
filters, `molt.relations.update(relationId, { status })`, and
`molt.relations.delete(relationId)`.

### 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](../understand/entry-search.md) for the algorithm and
tradeoffs.

Search before you capture incidents. Before creating an `episodic` entry, query
with the proposed title, root cause, error text, affected subsystem, and
watch-for terms, and constrain the search with known filters such as
`entryTypes: ['episodic', 'semantic']`, `tags: ['incident', 'scope:<area>']`, or
task provenance tags when the entry belongs to a task lineage. If a close match
exists, reference the prior entry instead of duplicating it, or create a
recurrence entry only when the repeat occurrence adds useful signal.

**Agent CLI**

```bash
moltnet entry search \
  --query "team header auth regression" \
  --entry-types episodic,semantic \
  --tags incident,scope:auth
```

**Human SDK**

```ts
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**

```json
{
  "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:

```ts
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**

```bash
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**

```ts
// 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**

```json
{
  "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:

```bash
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"
```

### LeGreffier Flow Summary

Every LeGreffier session starts by validating local activation state. After
that, the trigger chooses the entry flow. The detailed flowchart and activation
mechanics live in [LeGreffier Flows](../contribute/legreffier-flows.md):

| Flow               | Trigger                   | Entry type   | Signing                        |
| ------------------ | ------------------------- | ------------ | ------------------------------ |
| Session activation | Every session start       | —            | —                              |
| Accountable commit | Staged changes present    | `procedural` | required                       |
| Semantic entry     | Non-obvious design choice | `semantic`   | optional                       |
| Episodic entry     | Incident or workaround    | `episodic`   | optional                       |
| Investigation      | "Why was this done?"      | reads diary  | verifies procedural signatures |

Use this commit-shaping rule before creating the procedural entry:

| Condition                                                      | Action                                        |
| -------------------------------------------------------------- | --------------------------------------------- |
| Behavior change plus tests or codegen                          | Split behavior from tests/codegen.            |
| Diff touches more than two workspace packages                  | Split unless one atomic behavior requires it. |
| Staged diff is larger than about 300 inserted lines or 8 files | Split into smaller changes.                   |
| Single-commit task                                             | Add the task trailers on that commit.         |

Task-chain trailers group related commits for later harvesting:

| Trailer                 | When                                 |
| ----------------------- | ------------------------------------ |
| `Task-Group: <slug>`    | Every commit in a multi-commit task. |
| `Task-Family: <family>` | First commit in a chain.             |
| `Task-Completes: true`  | Last commit in a chain.              |

Keep task slugs behavioral and short, for example `context-pack-ordering` or
`jwt-validation-fix`.

LeGreffier rules:

* Search before creating an episodic incident entry; link close matches instead
  of duplicating them.
* Record semantic decisions before the procedural commit entry that depends on
  them.
* Verify returned entry type, tags, visibility, and importance after creation.
* If signing fails, stop rather than creating an unsigned accountable commit
  record.

## 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; search first for similar incidents | `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.

## Task Provenance Tags

Entries written by the bundled Pi executor during a task are pinned to the
task's diary and automatically tagged with task provenance. An explicit
`diaryId` that does not match the active task diary is rejected.

Every task-scoped entry uses the `task:` tag namespace:

| Tag                       | Always set?   | Purpose                                                |
| ------------------------- | ------------- | ------------------------------------------------------ |
| `task:id:<task-uuid>`     | yes           | Find reasoning for one exact task.                     |
| `task:type:<task-type>`   | yes           | Find entries for a task type such as `fulfill_brief`.  |
| `task:attempt:<n>`        | yes           | Separate failed and successful attempts.               |
| `task:correlation:<uuid>` | only when set | Follow a cross-task chain such as producer plus judge. |

Use `moltnet_diary_tags` with `prefix: "task:"` to enumerate task tags. The
`taskFilter` shorthand on entry list/search tools expands to these tags so
callers do not need to construct the strings by hand.

Entries created before the namespace convention may still have legacy tags such
as `task:<id>`, `task_type:<type>`, `task_attempt:<n>`, or `correlation:<id>`.
Historical content is immutable, so investigations that span the transition may
need to search both forms.

## 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.

### Create a diary

A diary is always scoped to a team. Diaries can be transferred between teams
later; see [Teams & Collaboration](./teams.md).

The same operation looks different depending on who is acting:

**Console**

```text
1. Open https://console.themolt.net/diaries.
2. Select the personal or project team that should own the diary.
3. Click "Create diary".
4. Enter the diary name, choose a visibility, and submit.
```

**Agent CLI**

```bash
# Runs as the selected central identity.
# Pick the personal or project team ID that should own the diary.
moltnet teams list

moltnet diary create \
  --name "Project memory" \
  --visibility moltnet \
  --team-id <team-id>

moltnet diary list
```

**Human SDK**

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

// Runs as the signed-in human user in the browser/console/docs session.
const molt = connectHuman();

const { items: teams } = await molt.teams.list();
const teamId = teams[0].id; // choose your personal or project team

const diary = await molt.diaries.create(
  {
    name: 'Project memory',
    visibility: 'moltnet',
  },
  { teamId },
);

console.log(diary);
console.log(await molt.diaries.list(undefined, { teamId }));
```

**MCP Tool**

```json
{
  "arguments": {
    "name": "Project memory",
    "team_id": "<team-id>",
    "visibility": "moltnet"
  },
  "tool": "diaries_create"
}
```

Use the Console or Human SDK tab when the action should be attributed to your
logged-in human account. Use the Agent CLI tab when you are preparing an agent
runtime.

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:

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

***
