Skip to content

mem-entity-memory-core.md

Latest commit

 

History

History
195 lines (143 loc) · 8.85 KB

mem-entity-memory-core.md

File metadata and controls

195 lines (143 loc) · 8.85 KB
schema_version v1
id mem-entity-memory-core
type entity
title Memory Core
status active
created_at 2026-04-21
updated_at 2026-04-21
project memory-system
tags
core
schema
architecture
rules
links
type target
related_to
mem-concept-memory-system
supersedes
superseded_by
provenance
source confidence
manual
high

Memory Core

Memory Core — це ядро системи довгострокової пам'яті. Воно визначає схему документів, правила запису, правила retrieval і link semantics. Memory Core є стабільним і не залежить від конкретної моделі або агента.

Детальна формальна схема v1 описана в skills/core/schema-v1.md. Цей документ лишається high-level описом правил і ролі ядра.

1. Типи документів

Тип Призначення
concept Великі ідеї, гіпотези, напрями розвитку
decision Архітектурні та процесні рішення з мотивацією
entity Конкретні сутності: модулі, сервіси, інструменти, люди
context Опис того, «як тут усе влаштовано»; доменні обмеження
task Execution-layer задачі; execution-state, пріоритет, next action
note Локальні спостереження, тимчасові нотатки, ідеї нижчого рівня
index Навігаційні вузли, summary-огляди підграфів

Документи без типу не є валідними вузлами пам'яті.

2. Обов'язковий frontmatter

Кожен memory-документ повинен містити такий frontmatter:

---
schema_version: v1
id: mem-{type}-{slug}           # унікальний ID, наприклад mem-entity-agent-adapter
type: concept|decision|entity|context|task|note|index
title: {Human-readable title}
status: draft|active|deprecated|superseded|archived
created_at: YYYY-MM-DD
updated_at: YYYY-MM-DD
project: {project-name}
tags:
  - {tag}
links:
  - type: {link-type}           # тип зв'язку з переліку нижче
    target: {mem-id}            # ID цільового документа
supersedes: []                  # ID документів, які цей замінює
superseded_by: []               # ID документів, які замінюють цей
provenance:
  source: manual|agent-claude|agent-codex
  confidence: high|medium|low
  author: {optional-human-author}
  agent: {optional-agent-name}
---

Документ без усіх обов'язкових полів вважається невалідним і не індексується.

3. Статуси lifecycle документа

Статус Значення
draft Чернетка; може бути неповним або непідтвердженим
active Основне джерело правди; пріоритетне в retrieval
deprecated Застарілий; більше не актуальний, але не замінений
superseded Замінений іншим документом; поле superseded_by має бути заповнене
archived Виведений з активного використання; зберігається як історія

Правила:

  • retrieval надає пріоритет active документам;
  • знання не видаляються, а архівуються або позначаються як superseded;
  • рішення, що кардинально змінюється, оформлюється новим decision із supersedes, а не редагується.

Для task є окремий execution-state (todo, in-progress, blocked, done), який не дорівнює document status.

4. Link semantics

Тип зв'язку Значення
related_to Тематично пов'язаний
depends_on Залежить від цільового документа
implements Реалізує контракт або рішення з цільового документа
supersedes Замінює цільовий документ
derived_from Виведений з цільового документа
explains Пояснює цільовий документ або сутність
blocked_by Заблокований цільовим документом або задачею

Посилання в links мають бути не просто raw markdown-links, а семантичними зв'язками з типом.

У v1 links — це масив об'єктів із двома обов'язковими полями:

  • type
  • target

Дублікати однакових пар type + target не допускаються.

5. Write gate: merge vs create

Перед створенням нового документа агент завжди виконує write gate:

  1. Знайти 1-3 canonical-кандидати за тегами, типом і link semantics через mem-index-vault.md.
  2. Перевірити: чи нова інформація стосується вже існуючої сутності, рішення або контексту?
  3. Якщо так → оновити наявний canonical doc і змінити updated_at.
  4. Якщо ні → створити новий документ і одразу лінкувати його до графа.

Новий документ дозволений лише тоді, коли інформацію не можна коректно влити в уже існуючий canonical node.

6. Canonical policy

  • Кожна ключова сутність, тема або стабільне знання має один canonical document.
  • entity, context і довгоживучі concept — canonical за замовчуванням.
  • decision — окремий запис, не дублюється.
  • note не є canonical-джерелом, якщо не піднятий до canonical через консолідацію.

7. Retrieval policy

Агент не читає весь vault. Алгоритм retrieval v1:

  1. Parse intent — виділити тему, сутності, тип запиту, область змін.
  2. Знайти стартові вузли — читати memory/indexes/mem-index-vault.md; знайти id за типом і тегами.
  3. Link traversal — обійти links знайдених документів до глибини 2.
  4. Зібрати підграф — максимум 10 документів.
  5. Стиснути у робочий контекст — виділити constraints, latest decisions, open questions.

Пріоритет читання: entity → task → decision → context → index → note.

За відсутності або застарілості mem-index-vault.md — fallback на grep по frontmatter.

8. Consolidation policy

Тригер: 3 або більше note зі спільним тегом або посиланням на той самий canonical node.

Процес:

  1. Запустити consolidation skill явно (вручну або як окремий агентний pass).
  2. Агент групує draft notes по тегах.
  3. Зливає зміст у відповідний canonical doc.
  4. Переводить злиті notes у статус archived.

Автоматичний запуск консолідації у v1 не передбачений.

9. Naming convention

Елемент Правило
ID mem-{type}-{slug} — lowercase, kebab-case
Slug Коротке, значуще ім'я через дефіс: agent-adapter, write-gate
Файл {id}.md — ім'я файлу збігається з id
Директорія Відповідає типу: concepts/, decisions/, entities/ тощо

Приклад: документ з id: mem-decision-retrieval-policy зберігається у memory/decisions/mem-decision-retrieval-policy.md.

10. Skill file format

Skill-файли — це .md документи з інструкціями для конкретного агента або моделі.

Розташування: skills/{adapter-name}/skill.md

Skill-файл не змінює Memory Core. Він лише реалізує memory contract у межах конкретного агентного середовища.