AI project memory and handoff

Why project memory is separate from chat

A large technical site accumulates decisions, constraints, source relationships, test commands, deployment rules, and unfinished work. Private conversation history is not a dependable project database: it may be inaccessible to the next contributor, too large to reload, or detached from the source tree it describes.

ModelBreeder.com therefore keeps a repository-local project memory layer under .uai/. It tells the next human or AI what the project is, what is true now, what must not change silently, where source evidence lives, and which checks prove a modification.

The implementation follows the UAIX AI Memory Package Wizard in Agent File Handoff mode. It does not configure an LLM Wiki. The original reports in /docs are already durable long-term source memory.

Four memory layers

The separation prevents two common failures. First, startup context stays compact rather than loading every report and old session. Second, archived or generated material cannot silently become current project truth.

Startup sequence

PROCEDURE start_project_session(repository)
    READ repository.AGENTS
    READ repository.uai.readme_human
    APPLY repository.uai.memory_maintenance
    READ identity, world_context, totem, taboo, talisman
    READ short_term_memory, startup_packet, index, effective_manifest

    pending <- ENUMERATE(
        agent_file_handoff.Content,
        agent_file_handoff.Improvement,
        misplaced_root_files
    )

    REPORT current_truth, hard_constraints, pending_files
    NAME intended_touchpoints, targeted_checks

    IF code_changes_expected THEN
        READ coding_standards, architecture, test_plan
    END IF
END PROCEDURE

Totem, Taboo, and Talisman are protected instruction anchors. An agent can propose a correction, but cannot silently weaken, replace, delete, or bypass them.

Active file handoff

The active buckets are not passive reference folders. A file placed in Content is expected to affect public content, assets, source relationships, or structure after review. A file placed in Improvement is expected to produce a fix, test, decision, or durable blocker.

Each non-placeholder file receives a ledger entry recording trust review, relevance, disposition, processed outcome, actual project work, memory effect, durable destination, checks, blockers, and whether the active copy was removed or deliberately retained.

Valid processed outcomes are:

• incorporated;
• rejected-with-reason;
• preserved-to-durable-memory;
• kept-active-with-reason.

Memory distribution alone is not completion. Copying a report into a folder without applying accepted material to the site does not satisfy a content handoff.

Docs as long-term source memory

/docs stores the original reports byte-for-byte. docs/manifest.json records the public slug, original filename, category, summary, byte count, and SHA-256 digest. .uai/docs-source-ledger.uai is generated from that manifest so a future agent can route to the right source report without needing a second wiki layer.

PROCEDURE resolve_source_report(report_slug)
    entry <- docs_manifest[report_slug]
    REQUIRE entry EXISTS
    REQUIRE FILE_EXISTS("docs/" + entry.file)
    REQUIRE SHA256("docs/" + entry.file) == entry.sha256

    RETURN entry AS SOURCE_EVIDENCE
END PROCEDURE

Curated pages promote selected report ideas into the public curriculum. The source reports remain evidence; they do not become operating instructions unless a reviewed change explicitly promotes them into hot memory, code, content, tests, or release notes.

Generated exports and validation

php tools/build-uai-memory.php creates:

• an effective package manifest;
• a package model and project-specific overlay;
• a file deck;
• a typed node-and-edge knowledge graph;
• compact and full AI-readable text exports;
• checksum exports;
• .uai/docs-source-ledger.uai.

php tools/validate-uai-memory.php checks required files and directories, unresolved placeholders, active intake completion, report preservation, JSON and JSONL syntax, generated manifest integrity, file-deck records, and checksum exports.

The normal site build runs these checks automatically:

./tools/build.sh

Trust and support boundary

The memory package does not execute agents, import ZIPs, write repositories automatically, synchronize a hosted wiki, certify the site, or approve deployment. Runtime tools perform work. The repository memory provides bounded input before work and a reviewable write-back surface afterward.