Skill Persistence (Procedural Memory)
Overview
Skills are the agent's procedural memory, they capture how to do a specific type of task based on proven experience. This is distinct from core memories (declarative facts about the user) and conversation history (recent context).
Pattern Origin
Adapted from Hermes Agent (tools/skill_manager_tool.py) and OpenClaw (extensions/memory-core/). Hermes uses filesystem storage (~/.hermes/skills/); we use PostgreSQL + RLS for multi-user cloud hosting.
Architecture
Storage
Skills live in the skills table with per-user isolation via RLS:
name: unique per user, lowercase with hyphensdescription: one-line summary (shown in skills index)category: optional groupingcontent: full procedure markdownversion: auto-incremented on save/patchtimesUsed/lastUsedAt: usage tracking
MCP Tools
Five tools registered in ajeris-tools:
| Tool | Action |
|---|---|
skill_save | Create or update a skill |
skill_list | List names + descriptions (progressive disclosure) |
skill_view | Load full content, bump usage counter |
skill_patch | Targeted edit (preferred for efficiency) |
skill_delete | Permanently remove |
System Prompt Integration
- SKILLS_GUIDANCE: Constant in system prompt telling the agent when to save skills (after 5+ tool calls, tricky errors, non-trivial workflows)
- Skills Index: Lightweight name+description list loaded into frozen session. Agent sees what skills exist without loading full content.
- Progressive Disclosure: Index in prompt (~50 tokens/skill) -> full content loaded on demand via
skill_view
Frozen Session
Skills index is loaded alongside memories when the frozen session is created (every 30 minutes). New skills saved during a session are available to the MCP tool immediately but don't appear in the prompt index until the next session.
Passive Extraction
The memory nudge (every 10 turns) now also considers skill extraction: "Did you solve something complex? Save it with skill_save."
Skill Format
## When to Use
Trigger conditions.
## Procedure
Step-by-step instructions.
## Pitfalls
Known failure modes.
## Verification
How to confirm it worked.SOUL.md (Personality)
The soul_config column on the users table stores a user-editable personality overlay. Updated via soul_update tool. Injected into the system prompt after the base personality block. Loaded once per frozen session.
Daily Notes
A scheduled task (daily-reflection, cron 0 23 * * *) reviews the day's conversations and saves observations as memories and skills. Fire-and-forget via the heartbeat scheduler.
Iteration Budget
Per-channel maxTurns limits:
- Voice: 6 (Alexa timeout pressure)
- SMS: 10 (default)
- Scheduled: 15 (background, no user waiting)
- Memory nudge: 5 (lightweight review)
Override via maxTurnsOverride in RunArgs for special cases.