| name | x-ipe-knowledge-keeper-memory |
| description | Unified write gatekeeper for persistent memory. Stores new knowledge entries and promotes working drafts to episodic, semantic, or procedural tiers. Delegates file I/O to scripts/memory_ops.py. Triggers on operations like "store", "promote". |
Keeper Memory — Knowledge Skill
Purpose
AI Agents follow this skill to perform memory write operations:
- Store new knowledge content to a persistent memory tier (episodic, semantic, procedural)
- Promote working drafts from
.working/ to a persistent memory tier
- Bootstrap memory folder structure when missing (auto-init)
Important Notes
BLOCKING: Operations are stateless services — the assistant orchestrator passes full context per call. Do NOT maintain internal state across operations.
CRITICAL: Each operation MUST define typed input/output contracts with a writes_to field.
CRITICAL: This skill is NOT directly task-matched. It is called by the Knowledge Librarian assistant (x-ipe-assistant-knowledge-librarian-DAO) or another assistant orchestrator.
CRITICAL: This skill handles FILE I/O ONLY. Ontology entity registration is performed by ontology-builder (FEATURE-059-C). Relationship maintenance is performed by ontology-synthesizer (FEATURE-059-D).
About
This skill serves as the single write gateway to persistent memory. All knowledge that needs to survive beyond a conversation session flows through keeper-memory's store or promote operations.
Key Concepts:
- Operation Contract — Each operation declares its input types, output types, writes_to path, and constraints. The orchestrator uses this contract to plan execution.
- Stateless Service — The skill receives all needed context from the orchestrator per call. No cross-operation memory.
- writes_to Discipline — Every operation declares
x-ipe-docs/memory/{memory_type}/ as its write target, enabling the orchestrator to predict side effects.
- File-Only CRUD — This skill writes/moves
.md content files. Ontology registration is a separate downstream step.
- Meaningful Slugs — Filenames derived from title (lowercase, hyphenated, max 60 chars), not from IDs.
When to Use
triggers:
- "Store new knowledge content to persistent memory"
- "Promote a working draft from .working/ to a memory tier"
- "Bootstrap memory folder structure"
not_for:
- "Searching or reading memory (use x-ipe-knowledge-extractor-memory)"
- "Ontology entity registration (use ontology-builder in 059-C)"
- "Web content extraction (use x-ipe-knowledge-extractor-web)"
Input Parameters
input:
operation: "store | promote"
context:
content: "string | structured"
memory_type: "episodic | semantic | procedural"
metadata: "dict"
tags: "string[]"
title: "string"
working_path: "string"
memory_type: "episodic | semantic | procedural"
metadata: "dict"
title: "string"
Input Initialization
BLOCKING: All input fields with non-trivial initialization MUST be documented here. Do NOT embed field initialization logic in operation steps.
<input_init>
<field name="operation" source="Assistant orchestrator specifies which operation to perform">
<validation>Must be one of: store, promote</validation>
</field>
<field name="context.memory_type" source="Assistant orchestrator specifies target tier">
<validation>Must be one of: episodic, semantic, procedural</validation>
</field>
<field name="context.title" source="Assistant orchestrator provides title for slug generation">
<validation>Non-empty string</validation>
</field>
<field name="context.content" source="Required for store operation">
<validation>Non-empty string or structured data</validation>
</field>
<field name="context.working_path" source="Required for promote operation">
<validation>Must exist and be within x-ipe-docs/memory/.working/</validation>
</field>
</input_init>
Definition of Ready
<definition_of_ready>
<checkpoint required="true">
<name>Operation specified</name>
<verification>input.operation is "store" or "promote"</verification>
</checkpoint>
<checkpoint required="true">
<name>Memory type valid</name>
<verification>context.memory_type is one of: episodic, semantic, procedural</verification>
</checkpoint>
<checkpoint required="true">
<name>Operation-specific inputs present</name>
<verification>store: content + title present; promote: working_path + title present</verification>
</checkpoint>
</definition_of_ready>
Operations
Operation: store
Contract:
- Input: content: string|structured, memory_type: "episodic"|"semantic"|"procedural", metadata: dict, tags: string[], title: string
- Output: stored_path: string, memory_entry_id: string
- Writes To: x-ipe-docs/memory/{memory_type}/
- Constraints: memory_type must be valid; bootstrap folders if missing; generate ID as {type_prefix}-{YYYYMMDD}-{sequence}; derive filename slug from title
When: Orchestrator needs to persist new knowledge content to a memory tier.
<operation name="store">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input context: content, memory_type, metadata, tags, title
2. DETERMINE target folder: x-ipe-docs/memory/{memory_type}/
3. CHECK if memory folder structure exists
</action>
<output>Input context understood, target folder identified</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE memory_type is one of: episodic, semantic, procedural
2. VALIDATE content is non-empty
3. VALIDATE title is non-empty string
4. IF memory folder missing → RUN `python3 scripts/init_memory.py` to bootstrap
</action>
<constraints>
- BLOCKING: Invalid memory_type → return error INVALID_MEMORY_TYPE with valid options
- BLOCKING: Empty content → return error INPUT_VALIDATION_FAILED
</constraints>
<output>Input validated, folders ready</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. DERIVE filename slug from title: lowercase, replace spaces/special chars with hyphens, max 60 chars
2. WRITE content to a temporary content file
3. RUN `python3 scripts/memory_ops.py create --type {memory_type} --title "{title}" --tags '{json_tags}' --metadata '{json_metadata}' --content-file {content_file} --memory-dir x-ipe-docs/memory`
4. CAPTURE output: stored_path, memory_entry_id
</action>
<output>Content file written, ID generated</output>
</phase_3>
<phase_4 name="明辨之 — Discern Clearly">
<action>
1. VERIFY file exists at stored_path
2. VERIFY file content matches input content
3. VERIFY memory_entry_id format matches {type_prefix}-{YYYYMMDD}-{sequence}
4. IF any verification fails → return error with details
</action>
<output>Output validated</output>
</phase_4>
<phase_5 name="笃行之 — Practice Earnestly">
<action>
1. RETURN operation_output:
- success: true
- operation: "store"
- result: { stored_path, memory_entry_id }
- writes_to: "x-ipe-docs/memory/{memory_type}/"
- errors: []
</action>
<output>Store operation complete, result returned to orchestrator</output>
</phase_5>
</operation>
Operation: promote
Contract:
- Input: working_path: string, memory_type: "episodic"|"semantic"|"procedural", metadata: dict, title: string
- Output: promoted_path: string
- Writes To: x-ipe-docs/memory/{memory_type}/
- Constraints: working_path must exist in .working/; original removed after move; target folder bootstrapped if missing
When: Orchestrator needs to promote a working draft to persistent storage.
<operation name="promote">
<phase_1 name="博学之 — Study Broadly">
<action>
1. READ input context: working_path, memory_type, metadata, title
2. DETERMINE source: x-ipe-docs/memory/.working/{working_path} or absolute path within .working/
3. DETERMINE target folder: x-ipe-docs/memory/{memory_type}/
</action>
<output>Input context understood, source and target identified</output>
</phase_1>
<phase_2 name="审问之 — Inquire Thoroughly">
<action>
1. VALIDATE working_path exists within x-ipe-docs/memory/.working/
2. VALIDATE memory_type is one of: episodic, semantic, procedural
3. VALIDATE title is non-empty
4. IF target folder missing → RUN `python3 scripts/init_memory.py` to bootstrap
</action>
<constraints>
- BLOCKING: working_path not found → return error PATH_NOT_FOUND
- BLOCKING: working_path not within .working/ → return error INVALID_PATH
</constraints>
<output>Input validated, paths confirmed</output>
</phase_2>
<phase_3 name="慎思之 — Think Carefully">
<action>
1. RUN `python3 scripts/memory_ops.py promote --path {working_path} --type {memory_type} --title "{title}" --metadata '{json_metadata}' --memory-dir x-ipe-docs/memory`
2. CAPTURE output: promoted_path
</action>
<output>File moved to target tier</output>
</phase_3>
<phase_4 name="明辨之 — Discern Clearly">
<action>
1. VERIFY file exists at promoted_path
2. VERIFY original file removed from .working/
3. IF any verification fails → return error with details
</action>
<output>Output validated</output>
</phase_4>
<phase_5 name="笃行之 — Practice Earnestly">
<action>
1. RETURN operation_output:
- success: true
- operation: "promote"
- result: { promoted_path }
- writes_to: "x-ipe-docs/memory/{memory_type}/"
- errors: []
</action>
<output>Promote operation complete, result returned to orchestrator</output>
</phase_5>
</operation>
Note on operations vs scripts: The store and promote operations define the cognitive flow (phases 博学之→笃行之) that the agent follows. The actual file I/O is performed by scripts/memory_ops.py. Additional CRUD operations (read, update, delete, list) are available directly via the script for programmatic use by other skills or the orchestrator, without needing a full SKILL.md operation wrapper.
Output Result
operation_output:
success: true | false
operation: "store | promote"
result:
stored_path: "x-ipe-docs/memory/{type}/{slug}.md"
memory_entry_id: "{prefix}-{YYYYMMDD}-{seq}"
promoted_path: "x-ipe-docs/memory/{type}/{slug}.md"
writes_to: "x-ipe-docs/memory/{memory_type}/"
errors: []
Definition of Done
<definition_of_done>
<checkpoint required="true">
<name>Operation completed successfully</name>
<verification>operation_output.success == true</verification>
</checkpoint>
<checkpoint required="true">
<name>Output written to declared path</name>
<verification>File exists at writes_to path with expected content</verification>
</checkpoint>
<checkpoint required="true">
<name>Output matches contract types</name>
<verification>stored_path/promoted_path is string; memory_entry_id matches pattern</verification>
</checkpoint>
<checkpoint required="true">
<name>Scripts functional</name>
<verification>init_memory.py and memory_ops.py execute without error</verification>
</checkpoint>
</definition_of_done>
Error Handling
| Error | Cause | Resolution |
|---|
INVALID_OPERATION | Operation name not "store" or "promote" | Return error listing valid operations |
INVALID_MEMORY_TYPE | memory_type not episodic/semantic/procedural | Return error listing valid types |
INPUT_VALIDATION_FAILED | Required input missing or wrong type | Return error with specific field |
PATH_NOT_FOUND | working_path doesn't exist (promote) | Return error with path details |
INVALID_PATH | Path not within .working/ (promote) | Return error explaining constraint |
WRITE_FAILED | Cannot write to target folder | Return error; orchestrator decides retry |
SLUG_CONFLICT | Generated filename already exists | Append numeric suffix (e.g., -2) |
Examples
See references/examples.md for usage examples.
