axmg-kernel (shelf) — Движок ассоциативной памяти на базе Merkle DAG

shelf — это встраиваемая, независимая и детерминированная Rust-библиотека ассоциативной памяти без использования векторных баз данных, эмбеддингов и нейросетевых словарей.

Она строит композитную память непосредственно из сырых байтовых потоков, используя криптографический Merkle DAG (SHA-256), динамику времени (Wheel), механизм фильтрации шума (Eviction $K=3$) и ассоциативный граф (PPMI + Recall).

🚀 Быстрый старт (Quickstart)

Добавьте библиотеку в ваш Cargo.toml:

[dependencies]
shelf = { path = "../shelf" }

1. Минимальный пример (In-Memory)

use axmg::Axmg;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Создаем движок в оперативной памяти
    let mut memory = Axmg::in_memory();

    // 2. Интегрируем поток фактов (горячий цикл: свертка, Surprise, вытеснение)
    let report = memory.ingest("Rust and Merkle DAG combine to build axmg")?;
    println!("Оборот: {}, Удивление: {:.3}, Вердикт: {:?}", 
        report.revolution, report.surprise_score, report.verdict);

    // 3. Извлекаем контекст активного фокуса внимания для системного промпта LLM
    let prompt_context = memory.prompt_context();
    println!("Prompt Context: {prompt_context}");

    // 4. Ассоциативный поиск (Recall)
    let recall = memory.recall("Merkle", Some(5));
    println!("Ассоциации: {}", recall.context_string);

    // 5. Оценка гипотезы без изменения памяти (Read-Only)
    let surprise = memory.check_surprise("Rust systems programming");
    println!("S-static: {:.3} | Вердикт: {:?}", surprise.s_static, surprise.verdict);

    Ok(())
}

Запустить готовый пример из репозитория:

cargo run -p shelf --example quickstart

💾 Режимы хранения

Режим 1: Полная персистентность (ACID на redb)

use axmg::Axmg;

// Открывает существующую базу или создает новую по указанному пути.
// Таймлайн автоматически пишется рядом в "agent_memory_timeline.jsonl".
let mut memory = Axmg::open("agent_memory.redb")?;

memory.ingest("Персистентное событие")?;
// Данные атомарно закоммичены на диск!

Режим 2: Гибкая конфигурация через AxmgBuilder

use axmg::{Axmg, AxmgBuilder, TieBreak};

let memory = AxmgBuilder::new()
    .db_path("custom_store.redb")
    .timeline_path("events.jsonl")
    .birth_threshold(2)               // Минимальная частота для рождения составного токена
    .tie_break(TieBreak::BirthOrder)   // Детерминированный порядок сортировки волн
    .focus_window(25)                 // Число топ-концептов в фокусе
    .auto_save(true)                  // Транзакционный сброс на каждом шаге
    .build()?;

🧠 Ключевые архитектурные концепции

🛠 Справочник API (Axmg)

Методы интеграции и записи

• engine.ingest(text: &str) -> Result<IngestReport, AxmgError> — интеграция строки с тегом "general".
• engine.ingest_tagged(text: &str, tag: &str) -> Result<IngestReport, AxmgError> — интеграция строки с пользовательским тегом.
• engine.ingest_bytes(bytes: &[u8]) -> Result<IngestReport, AxmgError> — интеграция сырых байт (логи, бинарные потоки).

Методы извлечения и поиска

• engine.recall(query: &str, limit: Option<usize>) -> RecallResponse — ассоциативный субграфный поиск концептов вокруг запроса.
• engine.focus() -> Arc<FocusSet> — мгновенный lock-free доступ к снапшоту активных токенов.
• engine.focused_concepts() -> &[FocusConcept] — срез топ-концептов текущего фокуса.
• engine.prompt_context() -> String — готовая строка активного контекста для внедрения в системный промпт LLM (экономия токенов 96.89%).

Диагностика и статистика

• engine.check_surprise(hypothesis: &str) -> SurpriseReport — проверка удивления без мутации хранилища.
• engine.stats() -> EngineStats — статистика: число токенов, коэффициент сжатия, доля фокуса.
• engine.timeline(limit: Option<usize>) -> Vec<TimelineEntry> — выборка последних событий таймлайна.
• engine.save() -> Result<(), AxmgError> — принудительный сброс на диск.

🛡 Фундаментальные инварианты библиотеки

1. Строгий детерминизм: Одинаковый поток байтов всегда порождает идентичные SHA-256 хеши и структуру Merkle DAG.
2. Смерть — это прекращение обращения, а не удаление: Тела токенов в Store неизменны (Append-only). Вытеснение фиксируется как лог событий Unfocus.
3. Безопасность типов: Никаких паник в библиотечном коде; все операции возвращают Result<T, AxmgError>.
4. Lock-Free чтение: Чтение фокуса внимания не блокирует входящий поток интеграции событий.

📖 Локальная документация (Rustdoc)

Сгенерировать и открыть интерактивную HTML-вики документацию с перекрёстными ссылками и сигнатурами:

cargo doc -p shelf --no-deps --open