portugalfuturista/replica-omnisciente
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 73
replica-omnisciente/sessions/2026-04-28_wiki-memory-layer-integration/implementation_plan.v15.md

12 KiB
Raw Permalink Blame History

Aurelio Token Optimization Plan: The Compiler Paradigm (Dirac, Tilth & TOON)

This plan focuses on transforming the Aurelio Hybrid Brain into an efficient "compiler" for human-AI interaction. Just as a C compiler converts natural language into machine code via an Abstract Syntax Tree (AST), Aurelio will pivot from processing raw strings to operating on the structural logic of the workspace.

The Aurelio Hybrid Universe Pipeline: The "Assembly Line"

We are shifting our hybrid universe to be "compiled" in the most efficient way possible, analogous to how a C compiler translates natural language (source code) into machine code. The AST serves as the "pivot point" where we stop looking at raw strings of text and start operating on the structural logic of the program.

Our hybrid agentic universe will strictly follow this assembly line:

  1. Lexical Analysis (Lexer): Breaks the context and requests into foundational "tokens" (e.g., int, main, (, {).

    • Aurelio Implementation: The system intercepts the user's natural language request and the workspace context. It uses TOON (Token-Oriented Object Notation) to represent structured data (like logs, search results, or configs) as dense, uniform tokens. This minimizes token consumption (~40% reduction) while clearly defining the semantic boundaries of the inputs.

  2. Syntax Analysis (Parser): This is where the AST is born. The parser takes those tokens and arranges them into a logical tree structure based on grammar rules.

    • Aurelio Implementation: Using Tilth's tree-sitter capabilities, Aurelio parses the workspace (prioritizing C, C++, Python, TypeScript, Rust). Instead of feeding raw file strings to the agent, it builds a structural outline (the AST) containing class and function signatures, giving the agent a precise architectural map of the codebase.

  3. Semantic Analysis: The compiler "walks" the AST to check for logical errors (e.g., type mismatches or undeclared variables).

    • Aurelio Implementation: The agent "walks" the codebase outline. It uses the aurelio_search tool (symbol-first search) to check for logical dependencies, ensuring intentions align with the established knowledge base and current state. This step guarantees that the agent understands how the code pieces fit together before writing anything. All metadata generated here is saved and synced centrally to the Proxmox server and .aurelio/brain.

  4. Code Generation: The compiler traverses the finished AST to produce assembly or machine code.

    • Aurelio Implementation: Acting as the machine code generator, the agent executes targeted, hash-anchored edits using Dirac's methodology. It surgically replaces specific AST nodes without needing to read or rewrite the entire file, guaranteeing absolute precision and massive token savings.

By integrating state-of-the-art techniques from dirac, tilth, and toon, our goal is to drastically reduce token consumption while maximizing agent reasoning capacity through this structural "compiler" paradigm.

User Review Required

Important

This plan introduces multiple paradigms (Standard, TOON, Tilth/Dirac) for interacting with files and data. We will keep the option to choose between paradigms, allowing the agent to evaluate and select the best philosophy based on the context and token constraints.

Token Characterization & Paradigm Selection

To dynamically choose the best paradigm, we will characterize the tokens being used:

  • Standard (JSON/Raw Text): Baseline token usage. Useful for deeply nested or non-uniform data where tabular formatting fails, or for very small files where overhead matters.
  • TOON (Token-Oriented Object Notation): Highly efficient for structured data, specifically uniform arrays of objects. Achieves ~40% fewer tokens than JSON. Ideal for transmitting list-like data (e.g., search results, logs, or structured configuration). All features and details of this TOON analysis will be applied globally across the central Proxmox server and all its associated MCP servers.
  • Tilth/Dirac (AST-Aware & Hash-Anchored): Optimal for large code files. Returns structural outlines instead of full files and uses hash-anchored edits, reducing the tokens spent on reading and replacing unmodified code. We will also implement a mechanism to save and sync the generated metadata (outlines, hashes) back to the Aurelio brain for long-term persistence and context recall.

Note: The choice between these paradigms will be actively configurable via the new settings and config panel in the Aurelio Control Center, giving developers full control over agent philosophy.

Proposed Changes

We will introduce a new suite of MCP tools hosted by the Aurelio brain, offering a multi-paradigm approach to file and data manipulation.

1. Smart Reading & Outlining (Tilth-inspired)

Modify the file reading pipeline to be context-aware based on file size.

[NEW] aurelio_read MCP Tool

  • Behavior: Parses file using tree-sitter. Priority languages: C, C++, Python, TypeScript, Rust.
    • Small files: Returns full content with line hashes.
    • Large files: Returns a structural outline (class and function signatures with line ranges).
  • Drill-down: Supports a section parameter to extract specific line ranges or headings as discovered in the outline.

2. Hash-Anchored Editing (Dirac & Tilth-inspired)

Replace line-number-based edits with extreme-precision hash anchoring to prevent "lost in translation" drift.

[NEW] aurelio_edit MCP Tool

  • Behavior: Edits are targeted using a hash generated during aurelio_read (e.g., 42:a3f| let x = compute();).
  • Validation: If the target line's hash has changed since the read, the edit is safely rejected and the updated content is returned to the agent.
  • Batching: Supports applying multiple edits across multiple files in a single tool call.

3. Symbol-First Search & Session Deduplication (Tilth-inspired)

Enhance searching to understand code structure rather than just text matching.

[NEW] aurelio_search MCP Tool

  • Behavior: Finds definitions and usages using AST queries. Instead of raw lines, it returns the semantic block (e.g., the whole function definition).
  • Callee Footer: Automatically appends a ── calls ── footer to definitions to show out-bound dependencies, reducing follow-up searches.
  • Session Deduplication: If a symbol's definition was already expanded in a previous search within the same session, it returns [shown earlier] instead of the full body.

[MODIFY] Centralized Session Memory Storage

  • Storage Location: Session deduplication state (tracking which symbols have been shown) will live centrally on the Proxmox server.
  • Implementation: The Aurelio MCP server will maintain an active cache keyed by Conversation ID to ensure consistent deduplication across different agent sessions and workspaces.

4. Structured Data Encoding (TOON-inspired)

Optimize the transmission of structured data (e.g., search results, diagnostic logs) between the MCP server and the agent.

[NEW] TOON Data Formatter

  • Behavior: Automatically formats compatible arrays of objects (e.g., list of file paths, search results, or database queries) into Token-Oriented Object Notation (TOON) before sending to the agent.
  • Token Savings: Combines YAML-like indentation with CSV-style tabular arrays to reduce token usage significantly.

5. Control Center Configuration & Interoperability

Create the central configuration hub within the Aurelio Control Center webview to manage the hybrid brain's behavior and external integrations.

[NEW] Main Configuration Panel

  • Paradigm Toggles: Provide UI switches to actively change the default file interaction paradigms (Standard, TOON, Tilth/Dirac).
  • Agent Interoperability: Add configuration fields and routing capabilities to allow Aurelio to interface with and utilize external agent systems. Supported integrations will include:
    • Cline
    • Roo Code
    • OpenCode
    • Claude Code
    • GitHub Copilot VS Code Extension
  • Customization: Centralize all agent behavior settings, API configurations, and prompt customizations.

6. UI Revamp & Premium Aesthetics (devicons)

Overhaul the Aurelio visual experience to feel more premium and integrated, replacing generic icons.

[MODIFY] Aurelio UI Asset Overhaul

  • Repository Integration: Pull the devicons repository (git@github.com:vorillaz/devicons.git) into the project assets.
  • SVG Implementation: Replace all current standard/lucide/vscode icons across the Control Center, Knowledge Tab, and other webviews with the high-quality SVG icons from the devicons library.
  • Theming: Ensure the new icons respect dynamic theme changes (Light/Dark modes) and enhance the "stunning first impression" aesthetic of the extension's webviews.

7. Knowledge Panel Refactoring & Reading Mode

Refactor the PDF, eBook, markdown (and other document types) visualizer and note-taking panel in the Control Center to provide a best-in-class reading and learning experience, inspired by Komga and Google Play Books.

[NEW] Immersive Reading Experience (Komga/Play Books style)

  • Document Visualizer: Implement a responsive, immersive reading mode for PDFs, EPUBs, and Markdown. Features should include page turning, continuous scroll, zooming, and a distraction-free full-screen mode.
  • Progress Tracking: Track and visually display reading progress (e.g., percentage read, last page accessed) across sessions.
  • Bookmarks & Annotations: Allow users to highlight text, draw on pages, and add inline comments seamlessly while reading.

[MODIFY] Note Extraction & "Absorbed Knowledge" Improvements

  • Fix Note Extraction Bug: Address the existing issue where users cannot extract notes. Ensure that notes taken during the reading session are robustly parsed and saved.
  • Fix Saved File Visibility Bug: Resolve the issue where saved note/knowledge files are not visible anywhere. Ensure these files are properly synced to the local .aurelio/brain/ and the Proxmox server, and displayed in the UI.
  • "Absorbed Knowledge" Dashboard: Create a dedicated view in the Knowledge Panel that synthesizes extracted notes, highlighted passages, and structural outlines from read documents into a coherent "knowledge graph" or timeline, making it easier for the agent and user to recall learned context.

Verification Plan

Automated Tests

  • Unit tests for the tree-sitter outliner across priority languages (C, C++, Python, TypeScript, Rust).
  • Integration tests simulating a hash-anchored edit where the underlying file is modified out-of-band to ensure the edit is correctly rejected.
  • Unit tests validating the TOON formatter against standard JSON output for token efficiency.
  • Unit tests for the document parsing and note extraction mechanisms.

Manual Verification

  • Deploy the updated Aurelio MCP server to mcp.portugalfuturista.org (CT 206).
  • Perform a complex refactoring task with an agent using the new aurelio_* tools and measure the token input/output against a baseline run using standard tools. We expect a ~40-60% reduction in token cost.
  • Launch the Aurelio VS Code Extension and verify that the Control Center configuration panel functions correctly, allowing dynamic paradigm switching.
  • Verify the UI aesthetics by confirming the devicons SVGs are correctly rendered across all extension webviews.
  • Open a PDF and an EPUB in the new Knowledge Panel, test the immersive reading mode, add highlights, and extract notes.
  • Verify that extracted notes and absorbed knowledge correctly appear in the "Absorbed Knowledge" dashboard and are physically saved/visible in the workspace.