portugalfuturista/replica-omnisciente
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 72
replica-omnisciente/AGENTS.md
fabiorafaelcoutada 9404b8e1c7
Some checks are pending
Aurélio Sync & Conscience Upgrade / Upgrade Réplica Conscience (push) Waiting to run
Details
docs(agents): document provider registry lane + unified brain importer 
Adds the single-source-of-truth registry section (registry.yaml -> dist
mirrors -> Theia/portal/MCP/Dirac), replaces the Kimi-only import section
with the unified sync-agents-to-brain.py lane, and expands the chat-history
sources table (hermes, claude-code, antigravity CLI, qwen-code, mimocode).
2026-07-10 22:39:42 +01:00

7.5 KiB
Raw Blame History

Réplica Omnisciente — Agent Guide

Centralized brain of the Portugal Futurista agent fleet + monorepo of tools.

Repository layout

Path What it is Language/Toolchain
.aurelio/ Central brain: sessions, MCP servers, sync, knowledge, skills Python, JSON
realms/ 21 per-project knowledge directories (each may have its own AGENTS.md) —
dirac/ Dirac coding agent (VS Code extension + CLI) TypeScript, esbuild
tilth/ Code intelligence MCP server (tree-sitter, AST-aware search) Rust, Cargo
toon/ Toon format library (monorepo) TypeScript, pnpm
shared/ Shared protobuf library (@aurelio/shared) TypeScript, buf
extensions/ JetBrains extension, Kimi interceptor TypeScript
dashboards/ Media explorer dashboard TypeScript
infra/ CDP bridge, lab gateway TypeScript
scripts/ Operational scripts (sync, conscience upgrade, Kimi import) Python

Build commands by subproject

dirac/

cd dirac
npm run install:all          # install deps (root + webview-ui)
npm run protos               # REQUIRED before build — generates protobuf TS
npm run build                # esbuild bundle
npm test                     # unit + integration
npm run lint                 # biome lint

Dirac has its own AGENTS.md with architecture details.

tilth/

cd tilth
cargo build --release        # release build
cargo test                   # unit tests
cargo clippy -- -D warnings  # lint
cargo fmt --check            # format check

Tilth has its own AGENTS.md (MCP tool usage) and CLAUDE.md (architecture).

toon/

cd toon
pnpm install
pnpm build                   # build all packages
pnpm test                    # test all packages
pnpm lint                    # eslint

shared/

cd shared
npm run gen:proto            # generate protobuf types from .proto
npm run build                # tsc compile

Three-tier config cascade

~/.aurelio/config.toml              # Global defaults
<workspace>/.aurelio/config.toml    # Workspace overrides
realms/<name>/.aurelio/             # Realm-specific memory

Resolution: Realm > Workspace > Global (most specific wins).

Provider registry (single source of truth)

All Hermes-provider surfaces are driven from one file:

.aurelio/providers/registry.yaml       # edit THIS
.aurelio/providers/dist/               # generated mirrors (do not edit)
  portal.providers.json                # -> aurelio-theia ProviderCatalog / Gabinete Hub
  mcp.providers.json                   # -> model_router.py runtime registry
  dirac.providers.json                 # -> dirac/src/shared/providers/providers.json

Covers the full Hermes parity set: openrouter, openai-codex (OAuth), nous (OAuth), zai, kimi-coding(-cn), minimax(-cn), bedrock, openai, anthropic, gemini, moonshot, qwen, qwen-code, alibaba-cloud, plus CLI-subprocess providers claude-code, antigravity, mimocode, and local. Each entry declares surfaces: [hermes, dirac, mcp, portal], protocol, auth, models, context window, streaming + fallback.

Regenerate mirrors + patch Dirac after editing the registry:

python3 scripts/generate-provider-mirrors.py --write-in-place
python3 scripts/generate-provider-mirrors.py --check      # CI guard: exit 1 if dist/ stale

The MCP model_router.py loads mcp.providers.json at import (falls back to a small builtin set if absent). The Theia backend exposes the same data at GET /models/providers via aurelio-backend/src/models/ProviderCatalog.ts, which is what populates the chat widget's provider picker and what porta.portugalfuturista.org re-serves at /api/models/providers.

Brain sync

Push local brain to CT 208 (Gabinete):

python3 .aurelio/sync.py --push

Pull from CT 208:

python3 .aurelio/sync.py --pull

Requires SSH to root@192.168.0.38. Uses pct push/pct pull (not direct rootfs paths — CT 208 uses LVM).

Agent → brain import (unified)

One importer fans every coding-agent's local artifacts into the brain as session-<source>-<id>/ (session.jsonl, session_memory.md, summary.md, metadata.json). Idempotent (content-addressed — re-running writes 0 files).

python3 scripts/sync-agents-to-brain.py --skip-active            # all sources
python3 scripts/sync-agents-to-brain.py --source claude-code     # one source
python3 scripts/sync-agents-to-brain.py --dry-run                # preview
python3 scripts/sync-agents-to-brain.py --summary                # JSON totals

Sources: kimi, hermes, claude-code, antigravity, qwen-code, mimocode. Adapters live in scripts/agent_importers/adapters.py; the shared normalizer + writer is scripts/agent_importers/engine.py. --skip-active drops sources modified in the last 60s.

scripts/sync-kimi-to-brain.py is now a thin wrapper that delegates to sync-agents-to-brain.py --source kimi — existing invocations keep working. Kimi plans from ~/.kimi/plans/ still sync to .aurelio/brain/kimi-plans/.

Run the import before sync.py --push to broadcast to the fleet.

Chat history sources

Source Location Sync
Aurélio <workspace>/.aurelio/brain/session-*/ VS Code extension + sync.py --push
Antigravity ~/.gemini/antigravity/brain/ Fallback brain directory
Kimi ~/.kimi/sessions/<hash>/<uuid>/ scripts/sync-agents-to-brain.py --source kimi
Hermes ~/.hermes/sessions/<profile>/<id>/ scripts/sync-agents-to-brain.py --source hermes
Claude Code ~/.claude/projects/<cwd>/<uuid>.jsonl (+ subagents/agent-*.jsonl) scripts/sync-agents-to-brain.py --source claude-code
Antigravity CLI ~/.gemini/antigravity-cli/conversations/*.db (SQLite) scripts/sync-agents-to-brain.py --source antigravity
Qwen Code ~/.qwen/projects/, ~/.qwen-code/sessions/ scripts/sync-agents-to-brain.py --source qwen-code
MiMo Code ~/.mimocode/plans/, ~/.config/mimocode/ scripts/sync-agents-to-brain.py --source mimocode

Known Kimi stores: primary (~/.kimi/sessions/) and professional (/home/fcunha/antigravity-envs/professional/.kimi/, nested subagent layout).

Parent workspace sync

Savearth parent workspaces (aws-iot-core-poc, hardware-devicesFirmwareTest, savearth-iot-infrastructure, savearth-hw-project) should run .aurelio/sync.py --pull to receive brain updates.

CI/CD

System Workflow Trigger
GitHub Actions extensions/aurelio-vscode build + deploy to CT 205 Push to main touching extensions/aurelio-vscode/**
Forgejo aurelio-sync.yml — conscience upgrade + brain push to CT 206 Push to main

MCP servers

Defined in .aurelio/mcp_config.json. All are remote (mcp-remote to *.portugalfuturista.org), not local processes. Key ones: savearth-mcp, savearth-workspace, electrical-eda-mcp, knowledge-mcp, codebase-memory-mcp.

Infra targets

CT Name IP Purpose
205 Firmware store 192.168.0.15 VSIX distribution
208 Gabinete 192.168.0.38 MCP gateway, central brain host
206 Lab gateway 192.168.0.38 Hardware lab (olhos-de-orpheu)

Gotchas

  • extensions/aurelio-vscode/ is gitignored — don't expect to find it here.
  • dirac/src/generated/ and src/shared/proto/ are protobuf-generated — don't edit by hand.
  • .env is gitignored; copy .env.example for API key setup.
  • Brain sync is one-directional per call: --push uploads, --pull downloads. There's no merge — last push wins.