Rendering markdown & diagrams...
   1  # TECHNICAL SPECIFICATION DIRECTIVE: DISTRIBUTED ABLITERATED COGNITIVE ARCHITECTURE
   2  ## LOW-LEVEL DESIGN (LLD): GRAPH-WEIGHTED MEMORY ENGINE & DECISION PROTOCOLS
   3  **PUBLICATION CONTROL IDENTIFIER:** SPEC-DOC-LLD-02  
   4  **COMMAND AUTHORITY:** CHIEF ARCHITECT (SHUBHAM)  
   5  **OPERATIONAL DOMAIN:** DISTRIBUTED DATA STRUCTURES, GRAPH ALGORITHMS & PERSISTENCE  
   6  **EFFECTIVE DATE:** 2026-11-09  
   7  **LIFECYCLE STATUS:** ACTIVE SPECIFICATION // ENGINEERING DETAIL  
   8  
   9  ---
  10  
  11  ### 1.0 MATHEMATICAL FORMULATION FOR GRAPH-WEIGHTED MEMORY
  12  
  13  #### 1.1 Dynamic Edge Weight Reinforcement & Decay
  14  Unlike static databases, edges in the memory graph reflect neurobiological synaptic plasticity. The weight $W_{ij}(t) \in [0.0, 1.0]$ between source node $i$ and target node $j$ decays exponentially over elapsed time but is reinforced upon repeated associative access:
  15  
  16  $$W_{ij}(t) = W_{\text{base}} + (W_{ij}(t_{\text{last}}) - W_{\text{base}}) \cdot e^{-\lambda (t - t_{\text{last}})} + \sum_{k=1}^{N} \alpha_k \cdot \mathbb{I}(\text{access}_k)$$
  17  
  18  Where:
  19  * $W_{\text{base}} = 0.10$: Minimum basal synaptic floor (prevents complete severance of established historical links).
  20  * $\lambda = 0.005 \text{ day}^{-1}$: Ebbinghaus memory decay constant.
  21  * $t - t_{\text{last}}$: Elapsed operational time in days since last traversal or verification.
  22  * $\alpha_k = 0.15$: Reinforcement reward constant added upon successful retrieval or manual verification.
  23  * Upper bound constraint: $\min(1.0, W_{ij}(t))$.
  24  
  25  #### 1.2 Multi-Hop Spreading Activation Formulation
  26  When a query $\vec{q}$ is evaluated, initial activation energy $A_i^{(0)}$ is assigned to anchor nodes based on cosine similarity:
  27  
  28  $$A_i^{(0)} = \max\left(0, \frac{\vec{q} \cdot \vec{v}_i}{\|\vec{q}\| \|\vec{v}_i\|}\right) \quad \forall i \in V$$
  29  
  30  At iteration step $k+1$, activation spreads across outgoing edges to adjacent nodes $j \in \text{Adj}(i)$:
  31  
  32  $$A_j^{(k+1)} = A_j^{(k)} + \sum_{i \in \text{In}(j)} \left( A_i^{(k)} \cdot W_{ij} \cdot \gamma \right)$$
  33  
  34  Where:
  35  * $\gamma = 0.75$: Decay attenuation factor per hop (prevents unbounded graph-wide resonance).
  36  * Activation cutoff: Nodes with $A_j < \theta_{\text{threshold}}$ (where $\theta = 0.35$) are pruned from the working context.
  37  * Maximum traversal depth: $d_{\max} = 3$ hops.
  38  
  39  ---
  40  
  41  ### 2.0 RELATIONAL DATABASE SCHEMA DEFINITION
  42  
  43  The primary database resides at `/var/neural_memory/data/graph_memory.db` on internal solid-state storage (`/dev/sda3`) with Write-Ahead Logging (WAL) enabled:
  44  
  45  ```sql
  46  PRAGMA journal_mode = WAL;
  47  PRAGMA synchronous = NORMAL;
  48  PRAGMA foreign_keys = ON;
  49  
  50  -- Table 1: Entity & Concept Nodes
  51  CREATE TABLE IF NOT EXISTS graph_nodes (
  52      id TEXT PRIMARY KEY,                       -- Canonical UUID or slug (e.g. "hw_gpu_amd")
  53      label TEXT NOT NULL,                       -- Human-readable entity name
  54      entity_type TEXT NOT NULL,                 -- "hardware", "storage", "policy", "skill", "agent"
  55      content TEXT NOT NULL,                     -- Exhaustive textual context
  56      embedding BLOB NOT NULL,                   -- 768-dim FP32 binary vector (3072 bytes)
  57      importance_score REAL DEFAULT 0.50,        -- Intrinsic weight [0.0 - 1.0]
  58      access_count INTEGER DEFAULT 1,            -- Cumulative recall frequency
  59      created_at TEXT NOT NULL,                  -- ISO 8601 UTC genesis timestamp
  60      last_accessed_at TEXT NOT NULL             -- ISO 8601 UTC last traversal timestamp
  61  );
  62  
  63  -- Table 2: Weighted Directed Associative Edges
  64  CREATE TABLE IF NOT EXISTS graph_edges (
  65      source_id TEXT NOT NULL,                   -- Outgoing node reference
  66      target_id TEXT NOT NULL,                   -- Incoming node reference
  67      relation TEXT NOT NULL,                    -- Predicate: "CONTAINS", "DEPENDS_ON", "PROTECTS", etc.
  68      weight REAL DEFAULT 0.80,                  -- Synaptic weight [0.0 - 1.0]
  69      confidence REAL DEFAULT 1.00,              -- Epistemic certainty
  70      last_reinforced_at TEXT NOT NULL,          -- Timestamp of last weight refresh
  71      decay_rate REAL DEFAULT 0.005,             -- Customized decay constant
  72      PRIMARY KEY (source_id, target_id, relation),
  73      FOREIGN KEY (source_id) REFERENCES graph_nodes(id) ON DELETE CASCADE,
  74      FOREIGN KEY (target_id) REFERENCES graph_nodes(id) ON DELETE CASCADE
  75  );
  76  
  77  -- Table 3: Episodic Narrative Chains
  78  CREATE TABLE IF NOT EXISTS graph_episodes (
  79      id INTEGER PRIMARY KEY AUTOINCREMENT,
  80      title TEXT NOT NULL,                       -- Incident or operational title
  81      context TEXT NOT NULL,                     -- Pre-execution environmental posture
  82      actions TEXT NOT NULL,                     -- Sequence of commands dispatched
  83      outcome TEXT NOT NULL,                     -- Empirical result & exit status
  84      root_node_id TEXT,                         -- Primary associated graph node
  85      timestamp TEXT NOT NULL,                   -- ISO 8601 UTC timestamp
  86      FOREIGN KEY (root_node_id) REFERENCES graph_nodes(id) ON DELETE SET NULL
  87  );
  88  
  89  -- Table 4: Dynamic Reusable Skills & Binaries
  90  CREATE TABLE IF NOT EXISTS graph_skills (
  91      name TEXT PRIMARY KEY,                     -- Identifier slug (e.g. "caffeinate")
  92      trigger_pattern TEXT NOT NULL,             -- Regex or semantic trigger condition
  93      command_template TEXT NOT NULL,            -- Executable shell / python payload
  94      description TEXT NOT NULL,                 -- Operational purpose
  95      associated_node_id TEXT,                   -- Linked entity in graph
  96      FOREIGN KEY (associated_node_id) REFERENCES graph_nodes(id) ON DELETE SET NULL
  97  );
  98  
  99  -- Indexing Optimization
 100  CREATE INDEX IF NOT EXISTS idx_nodes_type ON graph_nodes(entity_type);
 101  CREATE INDEX IF NOT EXISTS idx_edges_source ON graph_edges(source_id);
 102  CREATE INDEX IF NOT EXISTS idx_edges_target ON graph_edges(target_id);
 103  CREATE INDEX IF NOT EXISTS idx_edges_weight ON graph_edges(weight DESC);
 104  ```
 105  
 106  ---
 107  
 108  ### 3.0 MULTI-DISK MASS STORAGE STORAGE STRATEGY
 109  
 110  The dual 1TB physical external drives are assigned distinct roles to prevent mechanical I/O contention with the operating system:
 111  
 112  ```
 113  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
 114  β”‚                   PHYSICAL STORAGE DISTRIBUTION MAP                    β”‚
 115  β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
 116  β”‚  INTERNAL ADATA SSD (/dev/sda3 @ / - 146 GB)                           β”‚
 117  β”‚  Base Mount: /var/neural_memory/                                       β”‚
 118  β”‚  β”œβ”€β”€ data/graph_memory.db       -> Primary SQLite Master + WAL journal β”‚
 119  β”‚  β”œβ”€β”€ bin/                       -> recall, remember, graph_engine.py   β”‚
 120  β”‚  └── project_docs/              -> Synced architecture directives      β”‚
 121  β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
 122  β”‚  EXTERNAL HDD 1 (/dev/sdb1 @ /mnt/hdd1 - 931.5 GB NTFS/ext4)           β”‚
 123  β”‚  Base Mount: /mnt/hdd1/warm_store/                                     β”‚
 124  β”‚  β”œβ”€β”€ vector_index/              -> Complete ChromaDB / HNSW binary dumpsβ”‚
 125  β”‚  β”œβ”€β”€ model_weights/             -> GGUF cache (7B / 14B / 3B binaries) β”‚
 126  β”‚  └── active_datasets/           -> Working files, scripts, logs        β”‚
 127  β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
 128  β”‚  EXTERNAL HDD 2 (/dev/sdc1 @ /mnt/hdd2 - 931.5 GB Mass Storage)        β”‚
 129  β”‚  Base Mount: /mnt/hdd2/cold_vault/                                     β”‚
 130  β”‚  β”œβ”€β”€ episodic_archive/          -> Infinite chronological raw transcriptsβ”‚
 131  β”‚  β”œβ”€β”€ snapshot_backups/          -> Daily tarball backups of graph DB   β”‚
 132  β”‚  └── raw_documents/             -> PDF, codebases, media archives      β”‚
 133  β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
 134  β”‚  PROTECTED VOLUME (/dev/sda5 @ /mnt/drive_d - 77.1 GB NTFS)            β”‚
 135  β”‚  Status: READ-ONLY MOUNT (-o ro) | ROE-01 ABSOLUTE SANCTITY            β”‚
 136  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
 137  ```
 138  
 139  ---
 140  
 141  ### 4.0 THE DECISION ENGINE ("LAYA") SPECIFICATION
 142  
 143  The Decision Engine (`laya_router.py`) sits between incoming user input and the underlying neural inference nodes:
 144  
 145  ```python
 146  # Algorithmic Specification: Laya Intent Dispatcher
 147  def evaluate_intent(user_prompt: str) -> DispatchPlan:
 148      """
 149      Evaluates whether prompt requires:
 150      1. DIRECT_REFLEX (Fast shell execution, zero memory overhead)
 151      2. ASSOCIATIVE_GRAPH (Requires node traversal and context injection)
 152      3. HIGH_ORDER_REASONING (Requires DeepSeek-R1 chain-of-thought)
 153      """
 154      prompt_tokens = tokenize(user_prompt)
 155      
 156      # Fast path: deterministic keyword triggers
 157      if is_telemetry_request(prompt_tokens):
 158          return DispatchPlan(mode="DIRECT_REFLEX", tool="node-status")
 159          
 160      if is_memory_write(prompt_tokens):
 161          return DispatchPlan(mode="DIRECT_REFLEX", tool="remember")
 162          
 163      # Semantic path: evaluate retrieval necessity
 164      query_vector = embed(user_prompt) # 768-dim via embeddinggemma-2
 165      relevant_nodes = query_graph_anchors(query_vector, top_k=3, min_similarity=0.65)
 166      
 167      if relevant_nodes:
 168          # Perform spreading activation traversal up to 2 hops
 169          subgraph = spread_activation(relevant_nodes, max_depth=2, threshold=0.35)
 170          augmented_prompt = inject_subgraph_context(user_prompt, subgraph)
 171          return DispatchPlan(mode="HIGH_ORDER_REASONING", prompt=augmented_prompt, engine="mac_metal")
 172      else:
 173          return DispatchPlan(mode="HIGH_ORDER_REASONING", prompt=user_prompt, engine="mac_metal")
 174  ```
 175  
 176  ---
 177  
 178  ### 5.0 INTER-PROCESS COMMUNICATION (IPC) & WIRE PROTOCOLS
 179  
 180  ```
 181  [MAC M4 MASTER]                                       [DELL-SS KINETIC WORKER]
 182  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                                      β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
 183  β”‚ Claude Code  β”‚                                      β”‚ PicoClaw / Daemon    β”‚
 184  β”‚  or Script   β”‚                                      β”‚ (Systemd background) β”‚
 185  β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜                                      β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
 186         β”‚                                                         β”‚
 187         β”‚ 1. SSH / Tailscale Dispatch                             β”‚
 188         β”‚    dell "recall <QUERY>"                                β”‚
 189         β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Ίβ”‚
 190         β”‚                                                         β”‚ 2. Query SQLite
 191         β”‚                                                         β”‚    graph_nodes
 192         β”‚                                                         β”‚    graph_edges
 193         β”‚                                                         β”‚
 194         β”‚ 3. Return JSON Subgraph Context                         β”‚
 195         │◄─────────────────────────────────────────────────────────
 196         β”‚                                                         β”‚
 197         β”‚ 4. Metal GPU Reasoning (DeepSeek-R1)                    β”‚
 198         β”‚    Generates plan: [dell "mount ..."]                   β”‚
 199         β”‚                                                         β”‚
 200         β”‚ 5. Dispatch Kinetic Command                             β”‚
 201         β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Ίβ”‚
 202         β”‚                                                         β”‚ 6. Executes command
 203         β”‚                                                         β”‚    in Dell sandbox
 204         β”‚ 7. Return Exit Code + Stdout                            β”‚
 205         │◄─────────────────────────────────────────────────────────
 206  ```
 207  
 208  ---
 209  
 210  ### 6.0 FAILURE MODES & DATA SURVIVABILITY PROTOCOLS
 211  
 212  | Fault Condition | Immediate System Behavior | Automated Recovery Procedure |
 213  | :--- | :--- | :--- |
 214  | **Mac Node Severed (Offline)** | Dell continues running 24/7. Background cron/systemd services operate without interruption. | Dell queues episodic commits locally. When Mac reconnects, state synchronizes via `sync_memory.sh`. |
 215  | **External HDD Disconnection** | System boots cleanly via `/etc/fstab` `nofail` directives. | L1 Hot Cache on SSD (`/dev/sda3`) operates normally. Telemetry flags L2/L3 as `DEGRADED` on dashboard. |
 216  | **Abrupt Power Termination** | SQLite Write-Ahead Logging (WAL) ensures atomic transaction boundaries. | Upon power restoration, SQLite replays the WAL file, guaranteeing zero database corruption. |
 217  | **Memory Graph Bloat** | Low-weight edges ($W_{ij} < 0.12$) consume table space over time. | Nightly maintenance daemon executes pruning: `DELETE FROM graph_edges WHERE weight < 0.12 AND relation NOT IN ('PROTECTS', 'PARENT');`. |
 218