EXAMPLES.md
# session-history worked examples
## 1. Standard timeline
User: "Show me the session history."
Invocation:
```json
memory_sessions { "project": "app", "limit": 20 }
```
Response:
```json
{
"sessions": [
{ "id": "7f3a9c21", "project": "app", "startedAt": "2026-06-07T09:00:00Z",
"status": "completed", "observationCount": 14,
"summary": "Reworked refresh rotation",
"highlights": [ { "type": "decision", "title": "Rotate refresh tokens on every use" } ] },
{ "id": "b21d004e", "project": "app", "startedAt": "2026-06-05T14:00:00Z",
"status": "completed", "observationCount": 9,
"highlights": [ { "type": "code", "title": "limit.ts counts per-IP" } ] }
]
}
```
Present:
> - `7f3a9c2` app, 2026-06-07 09:00, completed, 14 obs
> - decision: Rotate refresh tokens on every use (summary: Reworked refresh rotation)
> - `b21d004` app, 2026-06-05 14:00, completed, 9 obs
> - code: limit.ts counts per-IP
## 2. Session with no observations
If a returned session has `observationCount: 0`, list it but say so:
> - `c98f110` app, 2026-06-04 11:00, abandoned, 0 obs (no recorded work)
## 3. Empty history
User: "What did we do last time?"
```json
memory_sessions { "project": "app", "limit": 20 }
```
Response:
```json
{ "sessions": [] }
```
Present:
> No recorded sessions yet for this project. Once you work with memory capture
> on, they will show here. Use `remember` to save a note now.
SKILL.md
---
name: session-history
description: Show what happened in recent past sessions on this project as a clean timeline. Use when the user asks "what did we do last time", "session history", "past sessions", or wants an overview of previous work.
user-invocable: true
---
The user wants an overview of recent sessions on this project.
## Quick start
```json
memory_sessions { "project": "<current-project-id>", "limit": 20 }
```
Expected output:
```text
7f3a9c2 · app · 2026-06-07 09:00 · completed · 14 obs
- decision: Rotate refresh tokens on every use
b21d004 · app · 2026-06-05 14:00 · completed · 9 obs
- code: limit.ts counts per-IP
```
## Why
Only show sessions and observations the tool returned. An empty history is a
real answer, never a cue to invent past work.
## Workflow
1. Use the exact project identifier recorded by the host and pass it to
`memory_sessions`, with `agentId` when requested. If it is unknown, page
through sessions using `nextCursor` and match normalized `cwd` by directory
boundary before choosing the most recent 20. Never substitute another project.
2. Preserve scope filters on every page; stop at the requested count or a null
`nextCursor`. State when the displayed history is a partial page. Present in
reverse chronological order: session id (first 8), project, start
time, status.
3. For sessions with observations, show the key highlights (type plus title).
4. Note the total observation count per session.
5. When a session summary exists, surface its title and the key decisions.
## Anti-patterns
WRONG: the tool returns two sessions, you describe "several sessions of steady
progress" and add ones you remember from the conversation.
RIGHT: show exactly the two sessions returned, each with its real id, status, and
observation count.
## Checklist
- Every session shown came from the tool response.
- Project/directory scope was checked before selecting the displayed window.
- Order is reverse-chronological.
- Per-session observation counts match the response.
- No session or highlight was invented or merged.
## See also
- `recap`: same data grouped by date with highlights.
- `handoff`: jump straight into the most recent session.
- `recall`: search across all sessions by topic.
## Troubleshooting
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if `memory_sessions` is not available.
TROUBLESHOOTING.md
<!-- AUTOGEN:troubleshooting START - generated by scripts/skills/generate.ts, do not edit by hand -->
# Troubleshooting agentmemory skills
Recovery steps for separately installed skills. This document is generated into
each skill directory so native skill readers can open it without parent traversal.
## "MCP tool not available"
Missing tools can mean a stopped MCP process, a disconnected daemon, or an
explicitly reduced tool surface. Walk these in order:
1. Identify the host. In Claude Code, inspect `/plugin list` and `/mcp`.
In Hermes, inspect the configured memory provider and `mcp_servers` separately.
In OpenClaw, validate the host configuration and inspect its MCP servers and
native plugins separately. In Pi or OMP, inspect `/agentmemory-status` and the
MCP inventory separately; native save/search does not prove the broader tools
are connected. Do not run another host's setup commands.
2. Restart or reload the affected host connection after configuration changes.
3. Inspect the connected tool inventory. Hermes may namespace MCP tools; invoke
the actual advertised names and schemas. A native memory provider is not
proof that every MCP tool or shared skill is available.
4. Check `agentmemory status` and the daemon's `AGENTMEMORY_TOOLS` setting.
Codex's bundled bridge lists the daemon's enabled tools. The standalone shim
used by other hosts can fall back to seven basic tools with a separate store.
Do not claim full daemon functionality based on those seven tools.
5. If `agentmemory connect codex` and the Codex plugin are both enabled, choose
one MCP connection. Check `/hooks` before adding global hook fallbacks.
Hermes, OpenClaw, Pi and OMP connector installations bundle skills; other hosts
may install them separately. Check the host's skill inventory and open this file
from the installed skill directory. Test automatic capture with a real turn and
a recorded observation; tool connectivity alone does not establish lifecycle
capture.
An outage or timeout is not an empty search result. Report the failure. A write
may have committed before the response was lost; inspect state before retrying.
## REST fallback
When the MCP tools stay unavailable but the daemon is running, call the REST
API directly:
1. Set `AGENTMEMORY_URL` to the daemon base URL (default `http://localhost:3111`).
2. The REST API requires a bearer credential by default. Use the host's explicit
`AGENTMEMORY_SECRET`; for loopback URLs only, fall back to the secret in
`~/.agentmemory/.env` and then `~/.agentmemory/secret`. Load the value locally
without displaying it. Never send a local-file secret to a remote URL.
If `AGENTMEMORY_CREDENTIAL_MODE=explicit`, require the explicit host credential
and do not read local credential files.
Authenticated REST fallback requests require HTTPS for non-loopback
URLs; HTTP is allowed for loopback URLs (`localhost`, `127.0.0.0/8`, or `[::1]`).
Reject redirects on authenticated requests. Do not print or save the secret.
Endpoint map by skill:
| Skill | REST call |
| --------------- | --------------------------------------------------------------- |
| remember | `POST /agentmemory/remember` |
| recall | `POST /agentmemory/smart-search` |
| recap | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search` |
| handoff | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search` |
| session-history | `GET /agentmemory/sessions` |
| commit-context | `GET /agentmemory/session/by-commit?sha=<sha>` |
| commit-history | `GET /agentmemory/commits` (URL-encode every query param) |
The MCP host reads the plugin MCP configuration. Restart the daemon after
changing its configuration, then restart or reconnect the host MCP process after
changing its URL or explicit secret. The local bridge reads the credential files
for each request; it does not inherit other daemon `.env` settings.
<!-- AUTOGEN:troubleshooting END -->