nac
777607dc29
Track the source-of-truth code, skills, bootstrap rules, docs, and packaging files before adding new features. Exclude local vault config, generated skill mirrors, temporary exports, virtual environments, and business data files from version control. Validation: inspected staged file list and git ignored status before commit.
132 lines
3.0 KiB
Markdown
132 lines
3.0 KiB
Markdown
# Hermes Agent — Data Format Reference
|
|
|
|
Field-level notes for parsing `~/.hermes/` artifacts during wiki ingest.
|
|
|
|
## Cache Root
|
|
|
|
`~/.hermes/` — or `$HERMES_HOME` for non-default profiles. All paths below are relative to this root.
|
|
|
|
## memories/
|
|
|
|
Each file is one discrete memory the agent persisted.
|
|
|
|
### Markdown memories (`*.md`)
|
|
|
|
Optional YAML frontmatter, then prose body:
|
|
|
|
```markdown
|
|
---
|
|
tags: [python, async, debugging]
|
|
created_at: 2026-03-10T14:22:00Z
|
|
project: my-api
|
|
---
|
|
When using `asyncio.gather` with return_exceptions=True, failed tasks return the exception
|
|
object rather than raising — check `isinstance(result, Exception)` on each item.
|
|
```
|
|
|
|
Fields of interest:
|
|
- `tags` — maps directly to wiki tags; normalize to kebab-case
|
|
- `created_at` — use for provenance / journal category decisions
|
|
- `project` — route to `projects/<project>/` when set
|
|
|
|
### JSON memories (`*.json`)
|
|
|
|
```json
|
|
{
|
|
"content": "...",
|
|
"created_at": "2026-03-10T14:22:00Z",
|
|
"tags": ["python", "async"],
|
|
"project": "my-api",
|
|
"source": "session:abc123"
|
|
}
|
|
```
|
|
|
|
Same field semantics as the markdown variant. `source` links back to the originating session.
|
|
|
|
## sessions/
|
|
|
|
Present only when session logging is enabled (`config.yaml: logging.sessions: true`).
|
|
|
|
### Directory layout
|
|
|
|
```
|
|
sessions/
|
|
└── 2026-03-10/
|
|
└── abc123.jsonl
|
|
```
|
|
|
|
### JSONL line schemas
|
|
|
|
**User / assistant turns:**
|
|
|
|
```json
|
|
{"role": "user", "content": "How do I debounce a React input?"}
|
|
{"role": "assistant", "content": "Use useCallback + useEffect with a setTimeout..."}
|
|
```
|
|
|
|
**Tool use:**
|
|
|
|
```json
|
|
{
|
|
"type": "tool_use",
|
|
"id": "tu_abc",
|
|
"name": "read_file",
|
|
"input": {"path": "/home/ubuntu/project/src/App.tsx"}
|
|
}
|
|
```
|
|
|
|
**Tool result:**
|
|
|
|
```json
|
|
{
|
|
"type": "tool_result",
|
|
"tool_use_id": "tu_abc",
|
|
"content": "..."
|
|
}
|
|
```
|
|
|
|
**Session metadata (first line):**
|
|
|
|
```json
|
|
{
|
|
"type": "session_meta",
|
|
"id": "abc123",
|
|
"cwd": "/home/ubuntu/projects/my-app",
|
|
"model": "claude-sonnet-4-6",
|
|
"started_at": "2026-03-10T14:00:00Z"
|
|
}
|
|
```
|
|
|
|
`cwd` is the most reliable project inference signal — use it to route knowledge to the right `projects/<name>/` page.
|
|
|
|
## config.yaml
|
|
|
|
Rarely useful for ingest. Useful fields if needed:
|
|
|
|
```yaml
|
|
model: claude-sonnet-4-6
|
|
hermes_home: ~/.hermes # resolved path, respects $HERMES_HOME
|
|
logging:
|
|
sessions: true # whether session JSONL files are written
|
|
memories: true # whether memories are persisted
|
|
```
|
|
|
|
## .hub/
|
|
|
|
Skills Hub state. **Skip entirely during ingest.** Contains:
|
|
|
|
- `lock.json` — installed skill manifest (not user knowledge)
|
|
- `audit.log` — install/update history
|
|
- `quarantine/` — flagged skills awaiting review
|
|
|
|
## Extraction Priority
|
|
|
|
| Source | Signal | Noise |
|
|
|---|---|---|
|
|
| `memories/*.md` | High — curated, stable | Low |
|
|
| `memories/*.json` | High — structured | Low |
|
|
| `sessions/**/*.jsonl` — assistant turns | Medium | Medium |
|
|
| `sessions/**/*.jsonl` — tool pairs | Low | High |
|
|
| `config.yaml` | Very low | — |
|
|
| `.hub/` | None | — |
|