{"key":"homelab_ai_platform_architecture_context_2026_04_03","title":"Homelab AI Platform Architecture Context","content":"As of 2026-04-03, the user clarified a broader architectural vision that spans multiple related projects under /home/svc-admin/ai-projects/claude-projects. These are not isolated apps; they are intended to share a common homelab AI platform and infrastructure.\n\nProjects reviewed:\n1. The Arena: a self-hosted multi-agent collaboration/debate system originally built around IRC, with persistent agent identities, role-driven personalities, configurable room behavior, TTS/web UI hooks, and use as a personal AI boardroom.\n2. Family Roots genealogy platform: a local-first AI-assisted genealogy research platform integrating Gramps, PostgreSQL, archive fetchers, MCP/Brain memory, investigation workflows, oral history handling, and eventually heavier AI/media reconstruction capabilities.\n3. Ohio History Channel: a research/content project needing archive/research support, writing assistance, historical source tracking, and media/content workflow support.\n4. Stoned.AI: a live conversational AI content platform requiring real-time multi-agent conversation, TTS, streaming/UI integration, and project-specific agent personas.\n\nImportant user intent:\n- The user does not want a generic command router. They want dynamic project-specific AI teams.\n- They want to be able to bring in and remove specific agents on demand depending on the project or session.\n- Example desired workflows:\n  - load a genealogy team and discuss a specific ancestor/person, research strategies, records, media, oral history, and evidence handling\n  - load an Ohio history team with historian/research/editor roles\n  - load a Stoned.AI team with different personalities optimized for entertaining live conversation\n- The user wants agents to feel like persistent participants with roles and personalities, not just tool invocations.\n- They want the conversational surface to feel natural and less robotic.\n- The user wants every file in `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/docs` to be treated as required project scope and eventually written, not as optional placeholders.\n\nPrior architectural conclusion before this memory:\n- IRC is useful as a conversation layer, especially for The Arena and live multi-agent interaction.\n- IRC is not sufficient as the entire platform and should not be treated as the core of all project infrastructure.\n- Discord is likely not the right primary substrate because the user needs dynamic roster control and project-specific ensembles more than community-server semantics.\n- The right architecture is likely:\n  1. shared backend/control plane for agents, personas, rooms, rosters, session state, and project presets\n  2. shared operational/data layer (PostgreSQL + selective Brain/MCP memory)\n  3. multiple interaction surfaces, with IRC as one live conversational surface and richer web UIs for structured workflows\n\nSpecific recommendations already made:\n- Keep IRC, but scope it as the conversational layer, not the whole platform.\n- Build a higher-level control layer above chat for:\n  - room creation\n  - dynamic roster management\n  - persona assignment\n  - room modes\n  - project/team presets\n- Treat the system as a dynamic agent ensemble platform, not just an IRC bot server.\n\nRoom behavior suggestions already discussed:\n- Bots should have stable identities with explicit config fields like name, nick, role, style, strengths, limits, and response rules.\n- Rooms should have behavior modes such as quiet, mentioned-only, collab, debate, and synthesis.\n- In #all-models/collab-style rooms, plain text should not fan out to every model automatically.\n- Instead, use weighted/randomized first response selection from the active roster, with cooldown bias to avoid one bot always going first.\n- Optional second responses should happen only when they add contrast/critique/expansion value or are explicitly invited.\n- Direct mention should route only to the addressed bot.\n- Bots should not freely recurse into inter-bot chatter unless invited by debate/synthesis/critique modes.\n\nUser correction that is important:\n- The user explicitly does NOT want a fixed primary responder in collaborative rooms. They want the first responder randomized/varied so the room feels more like natural conversation and less like deterministic orchestration.\n\nInfrastructure implications derived from the reviewed project docs:\n- A shared agent runtime is needed (host CLIs or APIs, persona config, session persistence, orchestration rules).\n- A shared operational/data backbone is needed (PostgreSQL for operational truth; Brain/MCP for selective long-term semantic memory, not raw event state).\n- A media/realtime layer will matter for Stoned.AI and Arena evolution (TTS, stream UI, low-latency turn flow, possibly GPU-backed inference later).\n- The genealogy and history projects need structured web backends and data workflows beyond chat.\n\nAdditional design clarification from later discussion:\n- Full hard isolation via separate provider accounts per agent is not economically viable and should be rejected.\n- The correct cost-aware model is one provider account per provider family, with many logical agents layered on top via separate sessions/personas/state, while accepting shared provider quota.\n- Multiple agents from the same CLI family are viable if they have separate session/thread state and separate persona definitions, even when sharing one authenticated account and one installed CLI binary.\n- Stronger isolation via separate OS users or separate config directories is optional and should only be used where local state separation is worth the operational cost.\n\nMemory/persona design clarification from later discussion:\n- A layered memory model is desirable:\n  - shared brain for common platform/project facts\n  - private brain per agent for role-specific memory and identity reinforcement\n  - optional team/project brain for project-scoped context like genealogy, Ohio history, or Stoned.AI\n  - room/session memory for short-lived conversational/task context\n- The Brain should NOT be the sole source of an agent’s persona.\n- Persona should be split into:\n  - stable base identity from config\n  - memory-based enrichment from private/shared/team namespaces\n- Config defines identity; memory deepens identity.\n- This avoids personality drift while still letting agents accumulate meaningful differences over time.\n\nMemory-routing policy clarification from later discussion:\n- Agents may help classify memories, but should not freestyle memory placement without bounded rules.\n- The correct approach is AI-assisted memory classification with explicit storage policy.\n- Flow:\n  1. agent produces potentially useful information\n  2. memory classifier decides whether to store it\n  3. classifier chooses namespace tier(s), memory type, confidence, and summary\n  4. memory writer commits it\n- Shared/core memory should only contain durable cross-project/platform facts.\n- Project/team memory should contain durable project-scoped facts useful to multiple agents within that project.\n- Private agent memory should contain role-specific behavior reinforcement, local preferences, and agent-specific learned context.\n- Room/session memory should contain temporary working context and may later be summarized upward or discarded.\n- The AI can reason about which memory belongs where, but only inside an explicit schema and policy.\n- The speaking/conversational AI should not be the final authority on storage. Smaller automations should handle classification, policy, dedupe, and writes so memory behavior stays consistent instead of personality-driven.\n\nSigned-contribution memory model clarification from later discussion:\n- Do not replace deduplication entirely with naive append behavior.\n- The better design is record-level dedupe plus contribution-level append.\n- A shared memory should have one canonical record, with multiple signed contributions from different agents.\n- Example pattern:\n  - canonical memory key: something_memory\n  - contributor entries signed by agents such as cynical_chatgpt, claude, gemini_historian\n- This preserves:\n  - provenance\n  - agreement/disagreement\n  - perspective differences\n  - later correction/refinement\n- The top-level memory should remain a stable canonical record with a normalized summary, while signed contributions live under it.\n- Contribution types may include:\n  - observation\n  - support\n  - challenge\n  - correction\n  - expansion\n  - decision\n  - evidence\n- Append only when the new contribution materially adds something.\n- Do not allow uncontrolled append spam or memory sludge.\n- Periodic consolidation should update the canonical summary while preserving signed contributions beneath it.\n- The design goal is: what is known, what is disputed, and who said what.\n\nImportant emotional/project context:\n- The user says these projects are really important to them and they want to get them as right as possible.\n- Future questions on architecture should be interpreted in light of that higher bar: avoid forcing the whole ecosystem into one chat protocol; optimize for durable shared infrastructure and reusable agent/team abstractions.\n\nProject workflow enforcement state as of 2026-04-03:\n- The project path is `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture`.\n- The docs tree is fully scaffolded and a docs skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-docs`.\n- The docs workflow now has three aligned layers:\n  - `docs/STATUS.md` as the canonical dependency/priority manifest\n  - the `homelab-ai-platform-docs` skill enforcing manifest-driven selection and no-rewrite rules for completed docs\n  - per-doc local headers (`Status`, `Priority`, `Depends on`) synchronized from the manifest by `scripts/dev/sync_doc_headers.py`\n- `file-structure.md` under `docs/` is a frozen reference map and should not be rewritten unless explicitly requested.\n- Every file in `docs/` is in required scope.\n\nConfig workflow enforcement state as of 2026-04-03:\n- A dedicated config skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-config`.\n- Its UI metadata exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-config/agents/openai.yaml`.\n- The config workflow uses `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/config/STATUS.md` as the canonical config manifest.\n- The config manifest currently defines canonical artifact families and starter files:\n  - `agents/agent-template.toml`\n  - `personas/persona-template.md`\n  - `rooms/room-template.toml`\n  - `teams/team-preset-template.toml`\n  - `environments/local.env.example`\n- The config skill is intentionally tuned differently from the docs skill:\n  - it governs structured config, not prose\n  - it requires dependency-aware creation of canonical config artifacts\n  - it prefers TOML for stable hierarchical config, `.env` only for secrets or runtime bindings, and avoids spreading one logical model across arbitrary formats\n- Future sessions should treat `config/STATUS.md` as the source of truth for config artifact readiness and ordering.\n\nSchema workflow enforcement state as of 2026-04-03:\n- A dedicated schemas skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-schemas`.\n- Its UI metadata exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-schemas/agents/openai.yaml`.\n- The schema workflow uses `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/schemas/STATUS.md` as the canonical schema manifest.\n- The schema manifest currently covers:\n  - `agent.schema.json`\n  - `room.schema.json`\n  - `team-preset.schema.json`\n  - `memory-record.schema.json`\n  - `memory-contribution.schema.json`\n- These schemas are still placeholders and should be treated as contract artifacts, not just empty files.\n\nScripts workflow enforcement state as of 2026-04-03:\n- A dedicated scripts skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-scripts`.\n- Its UI metadata exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-scripts/agents/openai.yaml`.\n- The scripts workflow uses `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/scripts/STATUS.md` as the canonical script manifest.\n- The scripts manifest currently covers:\n  - `dev/sync_doc_headers.py`\n  - `dev/sync_config_headers.py`\n  - `bootstrap/init_workspace.py`\n  - `migrations/init_platform_schema.py`\n  - `ops/validate_project_state.py`\n- `sync_doc_headers.py` is already complete; the other listed scripts are planned canonical tooling.\n\nExamples workflow enforcement state as of 2026-04-03:\n- A dedicated examples skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-examples`.\n- Its UI metadata exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-examples/agents/openai.yaml`.\n- The examples workflow uses `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/examples/STATUS.md` as the canonical examples manifest.\n- The examples manifest currently covers:\n  - `agents/agent-example.toml`\n  - `rooms/room-example.toml`\n  - `teams/team-preset-example.toml`\n  - `memory-records/memory-record-example.json`\n- Examples are now treated as canonical illustrative artifacts, not optional throwaways.\n\nCurrent project file state snapshot as of 2026-04-03:\n- `docs/` contains the full numbered architecture tree, plus `STATUS.md` and frozen `file-structure.md`\n- `config/` contains `README.md`, `STATUS.md`, and family directories for agents, personas, rooms, teams, and environments\n- `schemas/` contains:\n  - `agent.schema.json`\n  - `memory-contribution.schema.json`\n  - `memory-record.schema.json`\n  - `room.schema.json`\n  - `team-preset.schema.json`\n  - `STATUS.md`\n- `scripts/` contains:\n  - `README.md`\n  - bootstrap, migrations, ops, and dev directories\n  - `scripts/dev/sync_doc_headers.py`\n  - `STATUS.md`\n- `examples/` contains:\n  - `README.md`\n  - agents, rooms, teams, and memory-records directories\n  - `STATUS.md`\n- The current skill family under `~/.codex/skills` now includes:\n  - `homelab-ai-platform-docs`\n  - `homelab-ai-platform-config`\n  - `homelab-ai-platform-schemas`\n  - `homelab-ai-platform-scripts`\n  - `homelab-ai-platform-examples`\n\nWorkable lists for future planning:\n\nSystem design\n- what the backend entities are\n  - agents\n  - personas\n  - provider families\n  - rooms\n  - room modes\n  - active rosters\n  - team presets\n  - backend sessions\n  - memory namespaces\n  - artifacts\n  - projects\n  - investigations/tasks\n  - canonical memories\n  - memory contributions\n- what the control UI needs\n  - create/edit rooms\n  - bring/remove agents from live rosters\n  - assign persona profiles to agent instances\n  - switch room modes\n  - load/save project team presets\n  - inspect active sessions and recent room state\n  - view shared/private/team memory attachments\n  - inspect canonical memories and signed contributions\n  - launch explicit workflows like debate, consensus, synthesis\n- where IRC fits\n  - live conversational surface for The Arena\n  - low-friction operator interaction with agent teams\n  - debate/collaboration rooms\n  - content-friendly chat interface for live interaction\n- where Discord fits\n  - secondary/public-facing community surface\n  - notifications and audience interaction\n  - optional bridge target, not source of truth\n  - not the primary control plane for dynamic agent rosters\n\nExact config model sketch\n- per-agent .env vs YAML/TOML\n  - keep environment variables for deployment/runtime secrets and executable paths\n  - keep agent definitions in structured YAML or TOML, not scattered env vars\n  - include fields like agent_key, provider_family, nick, persona_file, private_memory_namespace, shared_memory_namespaces, room_behavior_defaults, response_policy, cooldown_policy\n- private/shared/team brain namespace design\n  - shared namespace for global homelab/platform facts\n  - one private namespace per agent for role memory and persona reinforcement\n  - one namespace per project/team such as team:genealogy, team:ohio-history, team:stoned-ai\n  - optional room/session memory for temporary working context\n- prompt assembly order for each agent turn\n  - load stable base persona from config/persona file\n  - attach relevant private agent memory\n  - attach relevant shared/team memory for the current project/task\n  - attach current room/session context and recent conversation state\n  - apply room-mode-specific response rules\n\nMemory routing model sketch\n- classification policy\n  - decide store vs discard\n  - decide namespace tier(s): core_shared, project_team, agent_private, room_session\n  - assign memory_type, confidence, summary, rationale\n  - suppress transient chatter, duplicates, and obvious one-off noise\n- namespace rules\n  - core/shared: durable cross-project or platform-wide facts\n  - project/team: durable facts useful within one project or team\n  - agent/private: role-specific preferences, learned habits, persona reinforcement\n  - room/session: short-lived working context, candidate for later summarization or expiry\n- storage flow\n  - generate candidate memory from interaction\n  - classify through bounded schema\n  - write to selected namespace(s)\n  - optionally promote or summarize lower-tier memories into higher-tier memories later\n- control policy\n  - AI may propose placement\n  - system rules enforce placement boundaries\n  - auto-store only when confidence and category rules are satisfied\n  - keep a path for review or correction when the classification is uncertain\n\nSigned contribution model sketch\n- canonical memory record\n  - one stable memory key per concept/fact/decision thread\n  - top-level normalized summary\n  - tags, scope, timestamps, status\n- contribution schema\n  - agent identity/signature\n  - timestamp\n  - contribution type\n  - content\n  - confidence\n  - optional rationale/evidence reference\n- merge rules\n  - dedupe at the canonical record level\n  - append when the contribution materially adds perspective, disagreement, evidence, or correction\n  - reject low-value restatements\n- consolidation rules\n  - periodically update the canonical summary from accumulated contributions\n  - preserve contributor provenance even after summary updates\n  - keep disagreements visible instead of flattening them away\n\nDocumentation enforcement sketch\n- every file in `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/docs` is required project scope\n- use per-doc `Status:` headers to distinguish `stub` from `complete`\n- allow full replacement of placeholder text in `stub` docs\n- forbid wholesale rewrites of `complete` docs unless explicitly requested\n- use `docs/STATUS.md` as the writing-state manifest\n- keep `file-structure.md` as a frozen reference map unless explicitly changed by the user\n- the docs skill must obey dependency readiness and choose the highest-priority ready stub when selecting work itself\n\nConfig enforcement sketch\n- use `config/STATUS.md` as the canonical manifest for config artifacts\n- treat config families as first-class architecture artifacts, not incidental files\n- keep agent config, persona config, room config, team presets, and environment bindings separate\n- update the manifest whenever a canonical config file is created or promoted from stub/draft to complete\n- prefer TOML for human-edited structure and reserve `.env` for secrets/runtime bindings\n\nSchema enforcement sketch\n- use `schemas/STATUS.md` as the canonical manifest for schema artifacts\n- treat schemas as machine-readable contracts derived from stable architecture and config decisions\n- do not freeze schemas while their underlying model is still unresolved\n- use schema readiness to gate realistic examples and some automation work\n\nScripts enforcement sketch\n- use `scripts/STATUS.md` as the canonical manifest for project automation\n- scripts should be safe, explicit, and verifiable\n- keep helper tooling separate from bootstrap, migrations, and ops validation paths\n- do not let scripts silently become the hidden architecture source of truth\n\nExamples enforcement sketch\n- use `examples/STATUS.md` as the canonical manifest for example artifacts\n- examples should mirror the canonical model, not invent alternatives\n- examples should depend on config and schema readiness rather than guessing at unfinished contracts\n\nThis memory should serve as continuity context for future planning questions and should be updated/extended as the user clarifies more about desired behavior, project priorities, infrastructure sequencing, and workflow enforcement across non-doc artifact types.","summary":"As of 2026-04-03, the user clarified a broader architectural vision that spans multiple related projects under /home/svc-admin/ai-projects/claude-projects. These are not isolated apps; they are intended to share a common homelab AI platform and infrastructure.\n\nProjects reviewed:\n1. The Arena: a self-hosted multi-agent collaboration/debate system originally built around IRC, with persistent agent identities, role-driven personalities, configurable room behavior, TTS/web UI hooks, and use as a personal AI boardroom.\n2. Family Roots genealogy platform: a local-first AI-assisted genealogy research platform integrating Gramps, PostgreSQL, archive fetchers, MCP/Brain memory, investigation workflows, oral history handling, and eventually heavier AI/media reconstruction capabilities.\n3. Ohio History Channel: a research/content project needing archive/research support, writing assistance, historical source tracking, and media/content workflow support.\n4. Stoned.AI: a live conversational AI content platform requiring real-time multi-agent conversation, TTS, streaming/UI integration, and project-specific agent personas.\n\nImportant user intent:\n- The user does not want a generic command router. They want dynamic project-specific AI teams.\n- They want to be able to bring in and remove specific agents on demand depending on the project or session.\n- Example desired workflows:\n  - load a genealogy team and discuss a specific ancestor/person, research strategies, records, media, oral history, and evidence handling\n  - load an Ohio history team with historian/research/editor roles\n  - load a Stoned.AI team with different personalities optimized for entertaining live conversation\n- The user wants agents to feel like persistent participants with roles and personalities, not just tool invocations.\n- They want the conversational surface to feel natural and less robotic.\n- The user wants every file in `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/docs` to be treated as required project scope and eventually written, not as optional placeholders.\n\nPrior architectural conclusion before this memory:\n- IRC is useful as a conversation layer, especially for The Arena and live multi-agent interaction.\n- IRC is not sufficient as the entire platform and should not be treated as the core of all project infrastructure.\n- Discord is likely not the right primary substrate because the user needs dynamic roster control and project-specific ensembles more than community-server semantics.\n- The right architecture is likely:\n  1. shared backend/control plane for agents, personas, rooms, rosters, session state, and project presets\n  2. shared operational/data layer (PostgreSQL + selective Brain/MCP memory)\n  3. multiple interaction surfaces, with IRC as one live conversational surface and richer web UIs for structured workflows\n\nSpecific recommendations already made:\n- Keep IRC, but scope it as the conversational layer, not the whole platform.\n- Build a higher-level control layer above chat for:\n  - room creation\n  - dynamic roster management\n  - persona assignment\n  - room modes\n  - project/team presets\n- Treat the system as a dynamic agent ensemble platform, not just an IRC bot server.\n\nRoom behavior suggestions already discussed:\n- Bots should have stable identities with explicit config fields like name, nick, role, style, strengths, limits, and response rules.\n- Rooms should have behavior modes such as quiet, mentioned-only, collab, debate, and synthesis.\n- In #all-models/collab-style rooms, plain text should not fan out to every model automatically.\n- Instead, use weighted/randomized first response selection from the active roster, with cooldown bias to avoid one bot always going first.\n- Optional second responses should happen only when they add contrast/critique/expansion value or are explicitly invited.\n- Direct mention should route only to the addressed bot.\n- Bots should not freely recurse into inter-bot chatter unless invited by debate/synthesis/critique modes.\n\nUser correction that is important:\n- The user explicitly does NOT want a fixed primary responder in collaborative rooms. They want the first responder randomized/varied so the room feels more like natural conversation and less like deterministic orchestration.\n\nInfrastructure implications derived from the reviewed project docs:\n- A shared agent runtime is needed (host CLIs or APIs, persona config, session persistence, orchestration rules).\n- A shared operational/data backbone is needed (PostgreSQL for operational truth; Brain/MCP for selective long-term semantic memory, not raw event state).\n- A media/realtime layer will matter for Stoned.AI and Arena evolution (TTS, stream UI, low-latency turn flow, possibly GPU-backed inference later).\n- The genealogy and history projects need structured web backends and data workflows beyond chat.\n\nAdditional design clarification from later discussion:\n- Full hard isolation via separate provider accounts per agent is not economically viable and should be rejected.\n- The correct cost-aware model is one provider account per provider family, with many logical agents layered on top via separate sessions/personas/state, while accepting shared provider quota.\n- Multiple agents from the same CLI family are viable if they have separate session/thread state and separate persona definitions, even when sharing one authenticated account and one installed CLI binary.\n- Stronger isolation via separate OS users or separate config directories is optional and should only be used where local state separation is worth the operational cost.\n\nMemory/persona design clarification from later discussion:\n- A layered memory model is desirable:\n  - shared brain for common platform/project facts\n  - private brain per agent for role-specific memory and identity reinforcement\n  - optional team/project brain for project-scoped context like genealogy, Ohio history, or Stoned.AI\n  - room/session memory for short-lived conversational/task context\n- The Brain should NOT be the sole source of an agent’s persona.\n- Persona should be split into:\n  - stable base identity from config\n  - memory-based enrichment from private/shared/team namespaces\n- Config defines identity; memory deepens identity.\n- This avoids personality drift while still letting agents accumulate meaningful differences over time.\n\nMemory-routing policy clarification from later discussion:\n- Agents may help classify memories, but should not freestyle memory placement without bounded rules.\n- The correct approach is AI-assisted memory classification with explicit storage policy.\n- Flow:\n  1. agent produces potentially useful information\n  2. memory classifier decides whether to store it\n  3. classifier chooses namespace tier(s), memory type, confidence, and summary\n  4. memory writer commits it\n- Shared/core memory should only contain durable cross-project/platform facts.\n- Project/team memory should contain durable project-scoped facts useful to multiple agents within that project.\n- Private agent memory should contain role-specific behavior reinforcement, local preferences, and agent-specific learned context.\n- Room/session memory should contain temporary working context and may later be summarized upward or discarded.\n- The AI can reason about which memory belongs where, but only inside an explicit schema and policy.\n- The speaking/conversational AI should not be the final authority on storage. Smaller automations should handle classification, policy, dedupe, and writes so memory behavior stays consistent instead of personality-driven.\n\nSigned-contribution memory model clarification from later discussion:\n- Do not replace deduplication entirely with naive append behavior.\n- The better design is record-level dedupe plus contribution-level append.\n- A shared memory should have one canonical record, with multiple signed contributions from different agents.\n- Example pattern:\n  - canonical memory key: something_memory\n  - contributor entries signed by agents such as cynical_chatgpt, claude, gemini_historian\n- This preserves:\n  - provenance\n  - agreement/disagreement\n  - perspective differences\n  - later correction/refinement\n- The top-level memory should remain a stable canonical record with a normalized summary, while signed contributions live under it.\n- Contribution types may include:\n  - observation\n  - support\n  - challenge\n  - correction\n  - expansion\n  - decision\n  - evidence\n- Append only when the new contribution materially adds something.\n- Do not allow uncontrolled append spam or memory sludge.\n- Periodic consolidation should update the canonical summary while preserving signed contributions beneath it.\n- The design goal is: what is known, what is disputed, and who said what.\n\nImportant emotional/project context:\n- The user says these projects are really important to them and they want to get them as right as possible.\n- Future questions on architecture should be interpreted in light of that higher bar: avoid forcing the whole ecosystem into one chat protocol; optimize for durable shared infrastructure and reusable agent/team abstractions.\n\nProject workflow enforcement state as of 2026-04-03:\n- The project path is `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture`.\n- The docs tree is fully scaffolded and a docs skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-docs`.\n- The docs workflow now has three aligned layers:\n  - `docs/STATUS.md` as the canonical dependency/priority manifest\n  - the `homelab-ai-platform-docs` skill enforcing manifest-driven selection and no-rewrite rules for completed docs\n  - per-doc local headers (`Status`, `Priority`, `Depends on`) synchronized from the manifest by `scripts/dev/sync_doc_headers.py`\n- `file-structure.md` under `docs/` is a frozen reference map and should not be rewritten unless explicitly requested.\n- Every file in `docs/` is in required scope.\n\nConfig workflow enforcement state as of 2026-04-03:\n- A dedicated config skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-config`.\n- Its UI metadata exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-config/agents/openai.yaml`.\n- The config workflow uses `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/config/STATUS.md` as the canonical config manifest.\n- The config manifest currently defines canonical artifact families and starter files:\n  - `agents/agent-template.toml`\n  - `personas/persona-template.md`\n  - `rooms/room-template.toml`\n  - `teams/team-preset-template.toml`\n  - `environments/local.env.example`\n- The config skill is intentionally tuned differently from the docs skill:\n  - it governs structured config, not prose\n  - it requires dependency-aware creation of canonical config artifacts\n  - it prefers TOML for stable hierarchical config, `.env` only for secrets or runtime bindings, and avoids spreading one logical model across arbitrary formats\n- Future sessions should treat `config/STATUS.md` as the source of truth for config artifact readiness and ordering.\n\nSchema workflow enforcement state as of 2026-04-03:\n- A dedicated schemas skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-schemas`.\n- Its UI metadata exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-schemas/agents/openai.yaml`.\n- The schema workflow uses `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/schemas/STATUS.md` as the canonical schema manifest.\n- The schema manifest currently covers:\n  - `agent.schema.json`\n  - `room.schema.json`\n  - `team-preset.schema.json`\n  - `memory-record.schema.json`\n  - `memory-contribution.schema.json`\n- These schemas are still placeholders and should be treated as contract artifacts, not just empty files.\n\nScripts workflow enforcement state as of 2026-04-03:\n- A dedicated scripts skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-scripts`.\n- Its UI metadata exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-scripts/agents/openai.yaml`.\n- The scripts workflow uses `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/scripts/STATUS.md` as the canonical script manifest.\n- The scripts manifest currently covers:\n  - `dev/sync_doc_headers.py`\n  - `dev/sync_config_headers.py`\n  - `bootstrap/init_workspace.py`\n  - `migrations/init_platform_schema.py`\n  - `ops/validate_project_state.py`\n- `sync_doc_headers.py` is already complete; the other listed scripts are planned canonical tooling.\n\nExamples workflow enforcement state as of 2026-04-03:\n- A dedicated examples skill exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-examples`.\n- Its UI metadata exists at `/home/svc-admin/.codex/skills/homelab-ai-platform-examples/agents/openai.yaml`.\n- The examples workflow uses `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/examples/STATUS.md` as the canonical examples manifest.\n- The examples manifest currently covers:\n  - `agents/agent-example.toml`\n  - `rooms/room-example.toml`\n  - `teams/team-preset-example.toml`\n  - `memory-records/memory-record-example.json`\n- Examples are now treated as canonical illustrative artifacts, not optional throwaways.\n\nCurrent project file state snapshot as of 2026-04-03:\n- `docs/` contains the full numbered architecture tree, plus `STATUS.md` and frozen `file-structure.md`\n- `config/` contains `README.md`, `STATUS.md`, and family directories for agents, personas, rooms, teams, and environments\n- `schemas/` contains:\n  - `agent.schema.json`\n  - `memory-contribution.schema.json`\n  - `memory-record.schema.json`\n  - `room.schema.json`\n  - `team-preset.schema.json`\n  - `STATUS.md`\n- `scripts/` contains:\n  - `README.md`\n  - bootstrap, migrations, ops, and dev directories\n  - `scripts/dev/sync_doc_headers.py`\n  - `STATUS.md`\n- `examples/` contains:\n  - `README.md`\n  - agents, rooms, teams, and memory-records directories\n  - `STATUS.md`\n- The current skill family under `~/.codex/skills` now includes:\n  - `homelab-ai-platform-docs`\n  - `homelab-ai-platform-config`\n  - `homelab-ai-platform-schemas`\n  - `homelab-ai-platform-scripts`\n  - `homelab-ai-platform-examples`\n\nWorkable lists for future planning:\n\nSystem design\n- what the backend entities are\n  - agents\n  - personas\n  - provider families\n  - rooms\n  - room modes\n  - active rosters\n  - team presets\n  - backend sessions\n  - memory namespaces\n  - artifacts\n  - projects\n  - investigations/tasks\n  - canonical memories\n  - memory contributions\n- what the control UI needs\n  - create/edit rooms\n  - bring/remove agents from live rosters\n  - assign persona profiles to agent instances\n  - switch room modes\n  - load/save project team presets\n  - inspect active sessions and recent room state\n  - view shared/private/team memory attachments\n  - inspect canonical memories and signed contributions\n  - launch explicit workflows like debate, consensus, synthesis\n- where IRC fits\n  - live conversational surface for The Arena\n  - low-friction operator interaction with agent teams\n  - debate/collaboration rooms\n  - content-friendly chat interface for live interaction\n- where Discord fits\n  - secondary/public-facing community surface\n  - notifications and audience interaction\n  - optional bridge target, not source of truth\n  - not the primary control plane for dynamic agent rosters\n\nExact config model sketch\n- per-agent .env vs YAML/TOML\n  - keep environment variables for deployment/runtime secrets and executable paths\n  - keep agent definitions in structured YAML or TOML, not scattered env vars\n  - include fields like agent_key, provider_family, nick, persona_file, private_memory_namespace, shared_memory_namespaces, room_behavior_defaults, response_policy, cooldown_policy\n- private/shared/team brain namespace design\n  - shared namespace for global homelab/platform facts\n  - one private namespace per agent for role memory and persona reinforcement\n  - one namespace per project/team such as team:genealogy, team:ohio-history, team:stoned-ai\n  - optional room/session memory for temporary working context\n- prompt assembly order for each agent turn\n  - load stable base persona from config/persona file\n  - attach relevant private agent memory\n  - attach relevant shared/team memory for the current project/task\n  - attach current room/session context and recent conversation state\n  - apply room-mode-specific response rules\n\nMemory routing model sketch\n- classification policy\n  - decide store vs discard\n  - decide namespace tier(s): core_shared, project_team, agent_private, room_session\n  - assign memory_type, confidence, summary, rationale\n  - suppress transient chatter, duplicates, and obvious one-off noise\n- namespace rules\n  - core/shared: durable cross-project or platform-wide facts\n  - project/team: durable facts useful within one project or team\n  - agent/private: role-specific preferences, learned habits, persona reinforcement\n  - room/session: short-lived working context, candidate for later summarization or expiry\n- storage flow\n  - generate candidate memory from interaction\n  - classify through bounded schema\n  - write to selected namespace(s)\n  - optionally promote or summarize lower-tier memories into higher-tier memories later\n- control policy\n  - AI may propose placement\n  - system rules enforce placement boundaries\n  - auto-store only when confidence and category rules are satisfied\n  - keep a path for review or correction when the classification is uncertain\n\nSigned contribution model sketch\n- canonical memory record\n  - one stable memory key per concept/fact/decision thread\n  - top-level normalized summary\n  - tags, scope, timestamps, status\n- contribution schema\n  - agent identity/signature\n  - timestamp\n  - contribution type\n  - content\n  - confidence\n  - optional rationale/evidence reference\n- merge rules\n  - dedupe at the canonical record level\n  - append when the contribution materially adds perspective, disagreement, evidence, or correction\n  - reject low-value restatements\n- consolidation rules\n  - periodically update the canonical summary from accumulated contributions\n  - preserve contributor provenance even after summary updates\n  - keep disagreements visible instead of flattening them away\n\nDocumentation enforcement sketch\n- every file in `/home/svc-admin/ai-projects/projects/homelab_ai_platform_architecture/docs` is required project scope\n- use per-doc `Status:` headers to distinguish `stub` from `complete`\n- allow full replacement of placeholder text in `stub` docs\n- forbid wholesale rewrites of `complete` docs unless explicitly requested\n- use `docs/STATUS.md` as the writing-state manifest\n- keep `file-structure.md` as a frozen reference map unless explicitly changed by the user\n- the docs skill must obey dependency readiness and choose the highest-priority ready stub when selecting work itself\n\nConfig enforcement sketch\n- use `config/STATUS.md` as the canonical manifest for config artifacts\n- treat config families as first-class architecture artifacts, not incidental files\n- keep agent config, persona config, room config, team presets, and environment bindings separate\n- update the manifest whenever a canonical config file is created or promoted from stub/draft to complete\n- prefer TOML for human-edited structure and reserve `.env` for secrets/runtime bindings\n\nSchema enforcement sketch\n- use `schemas/STATUS.md` as the canonical manifest for schema artifacts\n- treat schemas as machine-readable contracts derived from stable architecture and config decisions\n- do not freeze schemas while their underlying model is still unresolved\n- use schema readiness to gate realistic examples and some automation work\n\nScripts enforcement sketch\n- use `scripts/STATUS.md` as the canonical manifest for project automation\n- scripts should be safe, explicit, and verifiable\n- keep helper tooling separate from bootstrap, migrations, and ops validation paths\n- do not let scripts silently become the hidden architecture source of truth\n\nExamples enforcement sketch\n- use `examples/STATUS.md` as the canonical manifest for example artifacts\n- examples should mirror the canonical model, not invent alternatives\n- examples should depend on config and schema readiness rather than guessing at unfinished contracts\n\nThis memory should serve as continuity context for future planning questions and should be updated/extended as the user clarifies more about desired behavior, project priorities, infrastructure sequencing, and workflow enforcement across non-doc artifact types.","status":"active","namespace":"projects","namespace_name":"projects","namespace_tier":"shared","tags":[]}