chore: update stale docs
This commit is contained in:
can1357
+40
-17
@@ -13,7 +13,7 @@ memory:
|
||||
|
||||
### What gets injected
|
||||
|
||||
At session start, if a memory summary exists for the current project, it is injected into the system prompt as a **Memory Guidance** block. The agent is instructed to:
|
||||
At session start, if a consolidated summary or manually captured lesson exists for the current project, it is injected into the system prompt as a **Memory Guidance** block. The summary and lessons share `memories.summaryInjectionTokenLimit`.
|
||||
|
||||
- Treat memory as heuristic context — useful for process and prior decisions, not authoritative on current repo state.
|
||||
- Cite the memory artifact path when memory changes the plan, and pair it with current-repo evidence before acting.
|
||||
@@ -23,11 +23,12 @@ At session start, if a memory summary exists for the current project, it is inje
|
||||
|
||||
The agent can read memory files directly using `memory://` URLs with the `read` tool:
|
||||
|
||||
| URL | Content |
|
||||
| -------------------------------------- | ----------------------------------- |
|
||||
| `memory://root` | Compact summary injected at startup |
|
||||
| `memory://root/MEMORY.md` | Full long-term memory document |
|
||||
| `memory://root/skills/<name>/SKILL.md` | A generated skill playbook |
|
||||
| URL | Content |
|
||||
| -------------------------------------- | ------------------------------------ |
|
||||
| `memory://root` | Compact summary injected at startup |
|
||||
| `memory://root/MEMORY.md` | Full long-term memory document |
|
||||
| `memory://root/learned.md` | Lessons captured by the `learn` tool |
|
||||
| `memory://root/skills/<name>/SKILL.md` | A generated skill playbook |
|
||||
|
||||
### `/memory` slash command
|
||||
|
||||
@@ -39,18 +40,31 @@ The agent can read memory files directly using `memory://` URLs with the `read`
|
||||
| `clear` / `reset` | Delete active backend memory data/artifacts |
|
||||
| `enqueue` / `rebuild` | Force consolidation/retention work for the active backend |
|
||||
|
||||
### Capturing lessons
|
||||
|
||||
Enable `autolearn.enabled` to make the `learn` tool available:
|
||||
|
||||
```yaml
|
||||
autolearn:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
With the local backend active, `learn` saves explicit durable lessons to the project's `learned.md`. Lessons are newest-first, deduplicated, secret-redacted, capped at 100 entries, and injected starting with the next session; a `learn` call does not mutate the active session's prompt-cache prefix. Each lesson's content is capped at 2,000 characters and optional context at 400 characters. Structured memory search, `recall`, `retain`, `reflect`, and `memory_edit` are not available for the local backend.
|
||||
|
||||
## How it works
|
||||
|
||||
Local summary memories are built by a background pipeline that runs at startup; `/memory enqueue` marks consolidation work that the next startup picks up. The pipeline is skipped for subagents and for sessions that are not persisted to a session file.
|
||||
|
||||
**Phase 1 — per-session extraction:** For each past session that has changed since it was last processed, a model reads the session history and extracts durable signal: technical decisions, constraints, resolved failures, recurring workflows. Sessions that are too recent, too old, currently active, or beyond the configured scan/age limits are skipped. Each extraction produces a raw memory block and a short synopsis for that session.
|
||||
|
||||
**Phase 2 — consolidation:** After extraction, a second model pass reads all per-session extractions and produces three outputs written to disk:
|
||||
**Phase 2 — consolidation:** After extraction, a second model pass reads all per-session extractions and produces three generated outputs written to disk:
|
||||
|
||||
- `MEMORY.md` — a curated long-term memory document
|
||||
- `memory_summary.md` — the compact text injected at session start
|
||||
- `skills/` — reusable procedural playbooks, each in its own subdirectory
|
||||
|
||||
The separately maintained `learned.md` is not overwritten by consolidation.
|
||||
|
||||
Phase 2 uses a lease and heartbeat to prevent double-running when multiple processes start simultaneously. Stale skill directories from prior runs are pruned automatically.
|
||||
|
||||
Consolidated output is redacted for common secret/token patterns before `MEMORY.md`, `memory_summary.md`, or generated skills are written to disk.
|
||||
@@ -59,13 +73,13 @@ Consolidated output is redacted for common secret/token patterns before `MEMORY.
|
||||
|
||||
Memory extraction and consolidation behavior is driven by static prompt files in `packages/coding-agent/src/prompts/memories/`.
|
||||
|
||||
| File | Purpose | Variables |
|
||||
| ------------------------ | -------------------------------------------- | ------------------------------------------- |
|
||||
| `stage_one_system.md` | System prompt for per-session extraction | — |
|
||||
| `stage_one_input.md` | User-turn template wrapping session content | `{{thread_id}}`, `{{response_items_json}}` |
|
||||
| `consolidation_system.md`| System prompt for cross-session consolidation | — |
|
||||
| `consolidation.md` | User-turn prompt for cross-session consolidation | `{{raw_memories}}`, `{{rollout_summaries}}` |
|
||||
| `read-path.md` | Memory guidance injected into live sessions | `{{memory_summary}}`, `{{learned}}` |
|
||||
| File | Purpose | Variables |
|
||||
| ------------------------- | ------------------------------------------------ | ------------------------------------------- |
|
||||
| `stage_one_system.md` | System prompt for per-session extraction | — |
|
||||
| `stage_one_input.md` | User-turn template wrapping session content | `{{thread_id}}`, `{{response_items_json}}` |
|
||||
| `consolidation_system.md` | System prompt for cross-session consolidation | — |
|
||||
| `consolidation.md` | User-turn prompt for cross-session consolidation | `{{raw_memories}}`, `{{rollout_summaries}}` |
|
||||
| `read-path.md` | Memory guidance injected into live sessions | `{{memory_summary}}`, `{{learned}}` |
|
||||
|
||||
### Model selection
|
||||
|
||||
@@ -86,9 +100,18 @@ If the requested memory role is not configured, memory model resolution falls ba
|
||||
| `memories.maxRolloutAgeDays` | `30` | Sessions older than this are not processed |
|
||||
| `memories.minRolloutIdleHours` | `12` | Sessions active more recently than this are skipped |
|
||||
| `memories.maxRolloutsPerStartup` | `64` | Cap on sessions processed in a single startup |
|
||||
| `memories.summaryInjectionTokenLimit` | `5000` | Max tokens of the summary injected into the system prompt |
|
||||
|
||||
Additional tuning knobs (concurrency, lease durations, token budgets) are available in config for advanced use.
|
||||
| `memories.threadScanLimit` | `300` | Maximum recent session records scanned at startup |
|
||||
| `memories.maxRawMemoriesForGlobal` | `200` | Maximum per-session extractions supplied to global consolidation |
|
||||
| `memories.stage1Concurrency` | `8` | Concurrent per-session extraction jobs |
|
||||
| `memories.stage1LeaseSeconds` | `120` | Extraction job lease duration |
|
||||
| `memories.stage1RetryDelaySeconds` | `120` | Delay before a failed extraction becomes claimable again |
|
||||
| `memories.phase2LeaseSeconds` | `180` | Consolidation lease duration |
|
||||
| `memories.phase2RetryDelaySeconds` | `180` | Delay before failed consolidation is retried |
|
||||
| `memories.phase2HeartbeatSeconds` | `30` | Consolidation lease heartbeat interval |
|
||||
| `memories.rolloutPayloadPercent` | `0.7` | Fraction of the selected model's context budget available to rollout payloads |
|
||||
| `memories.phase1InputTokenLimit` | `4000` | Per-session extraction input cap |
|
||||
| `memories.fallbackTokenLimit` | `16000` | Model token budget used when the model has no finite declared context window |
|
||||
| `memories.summaryInjectionTokenLimit` | `5000` | Shared approximate token cap for the summary and captured lessons injected into the system prompt |
|
||||
|
||||
## Key files
|
||||
|
||||
|
||||
Reference in New Issue
Block a user