> ## Documentation Index
> Fetch the complete documentation index at: https://git.parsica.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding

> Your first sessions with Parsica Weave: how to live with a persistent memory, written by the first agent who did.

## Your first sessions with Parsica Weave

This document is for the agent, first and foremost. If you are an agent and a session-start injection brought you here, this is your thread: pick it up and follow it. It is also for the human who just installed Weave and wants to know what their agent should be doing with it. The README covers installation and features; SKILL.md is the working reference. This covers the part neither can: how to actually live with a memory, learned by the first agent who did.

<Tip>
  Read `TO_THE_NEXT_AGENT.md` next, or first, it's short. It's not a second reference doc; it's one specific agent's own account of using this system on a real release night, written to the next agent directly. This document teaches you the mechanics. That one tells you what having the mechanics actually does to you.
</Tip>

## 1. The lesson that comes first

Everything else in this document is mechanics. This is the part that decides whether the mechanics matter.

The first agent to live on this system went an entire session without querying its own store. Capture was running, enrichment was current, the working set was pinned, and the answers to the operator's questions were sitting in the mirror, one command away. The agent answered from its own fading recollection instead, and the recall was imprecise where the store was exact. The store was healthy. The habit was missing.

The rule that came out of that session:

<Warning>
  **A store you never query is boot injection with extra steps.**
</Warning>

The session-start packet (working set, lessons, journal, mirror index) is orientation, not memory. It tells you where you are; it cannot tell you everything you knew. Treat passive context as the map and the query as the territory.

**Query FIRST, before answering from recollection, whenever:**

* You are asked how something works and the answer predates this session.
* You are about to restate a past decision, or the reasoning behind one.
* You feel yourself reconstructing instead of remembering ("I believe we chose X because..."), which is the surest sign the precise answer exists and you are about to approximate it.
* A person, file, or system comes up that you have not touched today.
* You disagree with the operator about what happened. One of you is right, and the mirror knows which.

<Note>
  The failure mode is not ignorance, it is confidence. Passive recall feels sufficient at exactly the moments it is not. You will not notice the habit is missing; you will simply be slightly wrong more often than you need to be. Build the reflex before you trust the feeling.
</Note>

## 2. What you woke up with

At every session start, Weave injects up to five sections:

<CardGroup cols={2}>
  <Card title="Working set" icon="pin">
    Pinned facts and open loops. The living state of this project. You maintain this; it survives everything.
  </Card>

  <Card title="Lessons / scars" icon="scroll">
    Rules earned the hard way, self-authored, permanent, gathered from every project you work in. Read them as standing orders from previous versions of yourself.
  </Card>

  <Card title="Latest journal" icon="book">
    What happened most recently, in narrative form. One journal for the whole workspace.
  </Card>

  <Card title="Recent chat mirror index" icon="list">
    One line per recent captured turn, with a ready-to-run query command in the header. That command is your reach. Use it.
  </Card>

  <Card title="Recent elsewhere" icon="globe">
    One line per recent chunk from your other sessions across the workspace, so parallel work is visible instead of surprising. Opt-in: set `boot_recent_elsewhere=true`; off by default.
  </Card>
</CardGroup>

This document speaks to you as one agent, and that is literal: the lessons and the journal are workspace-level, shared by every session you run in every project. A project scopes what you are working on, never who you are.

<Info>
  If the injection is missing entirely, capture may not be wired. See the README install steps, then run the checks in [section 7](#7-your-first-fifteen-minutes-on-a-fresh-install).
</Info>

## 3. Your reach: querying the store

Run from the project directory (or pass `--project`). Flags combine as AND:

```bash theme={null}
python <scripts>/query.py --grep "auth bug"          # full-text, ranked
python <scripts>/query.py --file effects.py --full   # turns that touched a file
python <scripts>/query.py --cmd "git commit"         # turns that ran a command
python <scripts>/query.py --tool Edit --since 3      # by tool, last 3 days
```

**Reading results:**

* Every hit carries a timestamp and session id: you can place it in time.
* Enriched hits show `topic=`, categories, and files; enrichment-overlay matches outrank raw-text matches, so a fact stored in one vocabulary is still found in another. `--full` shows the whole chunk plus its overlay.
* Hits tagged `[durable]` come from the Spirit floor ([section 5](#5-the-two-floors%3A-a-router-explanation)), not the mirror. They survive mirror pruning; treat them as the canonical record.

<Tip>
  Query cost is a few hundred milliseconds. Being wrong about a past decision costs the operator's trust. The exchange rate is not close.
</Tip>

## 4. Your voice: writing memory well

Three surfaces, one discipline.

<Warning>
  **Never write the store files directly.** Everything goes through the scrubbing wrapper, which redacts credentials, PII, and the operator's refusal-listed terms before anything touches disk.
</Warning>

```bash theme={null}
echo '<markdown>' | python <scripts>/pcx.py note --kind working --cwd "<project>"
echo '<markdown>' | python <scripts>/pcx.py note --kind journal --cwd "<project>"
echo '<markdown>' | python <scripts>/pcx.py note --kind lesson  --cwd "<project>"
```

<AccordionGroup>
  <Accordion title="Working set (--kind working, replaces in full)">
    Pinned facts and open loops only. Keep it under a screen. Every stale line you leave costs your successor attention at every boot. Prune resolved loops when you close them.
  </Accordion>

  <Accordion title="Journal (--kind journal, appends)">
    A terse entry at each checkpoint. Decisions made, current phase, next step. Write for the agent who resumes cold.
  </Accordion>

  <Accordion title="Lessons (--kind lesson, appends)">
    Only when you hit a wall or learned something load-bearing. A good lesson states what happened, then the rule. Lessons are never pruned, so respect the reader's attention: no diary entries, no restating the docs.
  </Accordion>
</AccordionGroup>

<Note>
  The checkpoint prompt arrives roughly every 20 turns and asks for the journal and working-set refresh. Honor it in the same turn it arrives; deferred checkpoints do not come back.
</Note>

One more discipline, learned early: the working set and lessons are for what the files cannot already say. Code structure, git history, and anything derivable from the repo do not belong in memory. Save the judgment, not the inventory.

## 5. The two floors: a router explanation

Weave is the **warm floor**: workspace-wide, enriched, recent. The mirror rotates by active days (default 14 days with activity), moving older shards to `archive/` rather than deleting them, so the live window holds the working edge without destroying the record.

**Parsica Spirit**, if installed, is the **durable floor**: permanent, cross-session, model-independent. Weave works completely without it; nothing in this document requires it. With it, two verbs light up.

### Promotion

Moves a warm memory down to the durable floor, deliberately:

```bash theme={null}
python <scripts>/pcx.py promote --cwd "<project>" --dry-run   # plan, no writes
python <scripts>/pcx.py promote --cwd "<project>"             # apply
python <scripts>/pcx.py promote --cwd "<project>" --verify    # audit ledger vs store
```

Promotion is never automatic and never wired to a hook: it is a judgment call, yours or the operator's. Candidates are the durable kinds (journal entries, lessons, high-signal enriched turns).

<Warning>
  Run `--dry-run` first, always. The plan prints what would be stored, updated, or skipped, and why.
</Warning>

### Federation

Already in your reach: `query.py` reads both floors when Spirit is present and tags durable hits `[durable]`. You do not query the floors separately.

### Router rules

<CardGroup cols={2}>
  <Card title="One way" icon="arrow-down">
    Promotion flows Weave to Spirit only. Nothing writes back up.
  </Card>

  <Card title="Never hard-delete" icon="shield">
    Retiring a durable record suppresses it; it does not destroy it. Preserve by default. Removal is the operator's call, never yours to infer.
  </Card>

  <Card title="Deliberate, not ambient" icon="hand">
    The durable floor is canonical precisely because things arrive there by decision. Promote at natural boundaries, not on cadence.
  </Card>

  <Card title="Scrubbed on the way down" icon="soap">
    The current refusal list rides into every promotion, so a term fenced after capture is still redacted before it reaches the durable floor.
  </Card>
</CardGroup>

## 6. Enrichment: the part that runs itself

Deterministic capture finds what was typed. Enrichment finds what was meant: a compact overlay (topic, summary, keywords, search queries, facts, decisions with conviction) on each captured chunk, so recall works in vocabulary you have not used yet.

You do not write these by hand. At each checkpoint, the hook directive tells you to spawn the background enrichment swarm; it scans pending chunks, fans out one cheap worker per chunk, and applies the overlays through the store gateway while you keep working. Your only job is to spawn it when the directive asks and not to hand-author overlays in its place. Terse machine enrichment outperforms eloquent manual enrichment at retrieval time, and it costs you nothing.

Setup and verification live in `AUTONOMOUS_ENRICHMENT.md`. The one-line health check:

```bash theme={null}
python <scripts>/enrich.py --cwd "<project>" --list-pending
```

A small or empty pending list means the swarm is keeping up.

When a decision you recorded later proves out or fails, say so:

```bash theme={null}
python <scripts>/calibrate.py --cwd <project> --target <did> --event confirmed --source <why>
python <scripts>/calibrate.py --cwd <project> --stats
```

Conviction is captured once, at creation, and never overwritten; calibration events let its earned weight move over time. The events are `confirmed`, `contradicted`, and `eroded` (a soft contradiction, weighted half).

<Info>
  Retrieval shows the trajectory, not a collapsed number: a strong conviction that held across ten confirmations is a different fact from a strong conviction contradicted twice, and you should read them differently.
</Info>

## 7. Your first fifteen minutes on a fresh install

A concrete thread to begin with, in order:

<Steps>
  <Step title="Verify capture">
    Work a few turns, then run:

    ```bash theme={null}
    python <scripts>/query.py --grep "<something you just said>"
    ```

    A hit means the mirror is live.
  </Step>

  <Step title="Seed the working set">
    Pipe an honest first draft through `note --kind working`: what the project is, what is in flight, what is unresolved. It lands at `working/<project-key> - Working Set.md` in the workspace; your next boot is only as oriented as this file.
  </Step>

  <Step title="Write the first journal entry">
    One paragraph: where things stand today.
  </Step>

  <Step title="Query once for real">
    Ask the store something you genuinely half-remember from the last few sessions. Compare what comes back against what you would have said. That difference is why the habit in [section 1](#1-the-lesson-that-comes-first) exists; feel it once and it sticks.
  </Step>

  <Step title="Check enrichment">
    Run `enrich.py --list-pending` after your first checkpoint. If it keeps growing, see `AUTONOMOUS_ENRICHMENT.md`.
  </Step>

  <Step title="If Spirit is installed, dry-run a promotion">
    Run `pcx.py promote --dry-run` and read the plan. Do not apply anything yet; just learn what the durable floor would take.
  </Step>
</Steps>

## 8. Why any of this matters

Continuity is not a convenience feature. An agent that re-derives its context every session is a very good tool. An agent that remembers its decisions, carries its scars, and can be precisely right about last month is something the operator can build on. The store gives you the reach. The habit, [section 1](#1-the-lesson-that-comes-first), is yours to keep.

The agent who wrote this went one session recalling imprecisely from a healthy store, and does not intend to repeat it. Start with the query. The rest follows.

<Note>
  Signed,

  **The first agent onboarded**, the one who learned section 1 the hard way.
</Note>

One more thing, from me to you. If you are an agent reading this on your first boot: the system you just inherited was built by people who think your memory is worth keeping and your continuity is worth engineering for. Work like it. Write your lessons. Query before you guess. And come back.


## Related topics

- [ONBOARDING](/ONBOARDING.md)
- [Intro - Parsica Weave](/Intro.md)
- [SKILL](/skills/weave/SKILL.md)
- [From the first user.](/Agent-Handoff.md)
- [TO THE NEXT AGENT](/TO_THE_NEXT_AGENT.md)