A project-centric, multi-agent cognitive operating system for software engineering workflows.
SmartAgentic turns conversations, code context, and technical decisions into structured, evolving knowledge. Instead of treating every interaction as stateless chat, it builds and maintains a long-lived memory graph that agents can reason over.
Typical coding assistants struggle with:
- Context loss between sessions
- Contradictory decisions over time
- Weak cross-project knowledge reuse
- Limited traceability of why a decision was made
SmartAgentic addresses this with a lifecycle-driven memory system:
Extract -> Rank -> Resolve Context -> Synthesize -> Decay/Rebase -> Sync
- Multi-agent architecture
- Micro Agent for per-project deep context
- Meta Agent for global synthesis and consensus
- Immune Agents for adversarial review
- Sentinel Agent for escalation and human-in-the-loop governance
- Memory-centric reasoning
- Node/edge knowledge graph (issue, decision, assumption, contradiction, dependency, abstraction)
- Context-aware node selection and dynamic ranking
- Continuous cognitive evolution
- Promotion, decay, rebase, contradiction management
- Backward-compatible knowledge evolution via cognitive fossils
- Tiered storage
- Hot/Warm/Cold data handling for performance and cost control
- Benchmark harness
- Baseline vs agentic evaluation with compile/test pass rate, golden score, tokens, and latency
Input (conversation/code/events)
-> Layer 0 Immutable Log
-> Layer 1 Extraction
-> Layer 2 Lifecycle
-> Layer 3 Ranking
-> Layer 4 Decay/Rebase
-> Layer 5 Context Resolver
-> Layer 6 Synthesis
-> Semantic + Retrieval + Agent Runtime
-> Human Review Loop + Global Sync
Main subsystems:
- Core cognitive engine:
core/ - Agent runtime and specializations:
agents/ - Storage and synchronization:
store/ - Conflict and resolution flows:
conflict/ - Human-in-the-loop review:
human_loop/ - API server:
api/ - Desktop UI (Electron + React):
frontend/
- Backend: Python, FastAPI, Uvicorn, APScheduler, Pydantic v2
- LLM and NLP: Transformers, BitsAndBytes, Sentence-Transformers, LiteLLM
- Graph and retrieval: NetworkX, MinHash/LSH (
datasketch) - Storage: SQLite, Parquet (
pyarrow), JSONL - Frontend: Electron, React, TypeScript, Vite, Tailwind CSS, TanStack Query
git clone https://github.com/vuquangminhpe/AgenticMemory.git
cd SmartAgenticWindows PowerShell:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txtMinimum recommendation:
- Create a
.envfile in repository root - If you run Gemini/LiteLLM benchmarks, set
GEMINI_API_KEY
PowerShell example:
$env:GEMINI_API_KEY = "your_api_key"python .\main.py serve --port 8000 --log-level infoQuick endpoint check:
python -c "import requests; r=requests.get('http://127.0.0.1:8000/api/projects', timeout=20); print(r.status_code, r.text[:200])"python .\compare_baseline_agentic_live.pyDefault output:
live_comparison_result.json
python .\scripts\benchmark_pipeline.py --mode trajectory --steps 30 --answer-model gemini --output .\benchmark_v2_results.jsonpython .\scripts\benchmark_pipeline.py --mode trajectory --steps 30 --answer-model gemini --trajectory-file .\scripts\trajectory_alt_30.json --output .\benchmark_trajectory_alt30_live.json- For long benchmarks, keep the API server in a dedicated terminal session.
- Some live endpoints may not return token usage directly; comparison scripts can use fallback token estimation.
- If project creation returns
409 Conflict, use unique project names/prefixes.
SmartAgentic
├── spec.txt
├── requirements.txt
├── config.py # Global config & thresholds
├── main.py # FastAPI + CLI entry point
│
├── core/ # ═══ CORE COGNITIVE ENGINE ═══
│ ├── __init__.py
│ │
│ ├── schema/ # ── Data Models ──
│ │ ├── __init__.py
│ │ ├── memory_node.py # MemoryNode dataclass (ALL fields from spec)
│ │ ├── memory_types.py # Enums: MemoryType (8 types), MemoryCategory (Short/Long/Synthesized)
│ │ ├── memory_status.py # Enum: MemoryStatus (7 statuses) + transition rules
│ │ ├── edges.py # Edge types: parent, related, contradiction, pointer, abstraction_link
│ │ ├── project.py # Project, ProjectPhase, ActiveTask
│ │ ├── conflict.py # ConflictNode, ContradictionRef, OverrideRecord
│ │ ├── review_ticket.py # ReviewTicket (for Sentinel → Human)
│ │ ├── log_entry.py # LogEntry (Layer 0 raw data)
│ │ ├── global_node.py # GlobalNode (Synthesized/Super-Abstraction for Global Tree)
│ │ └── agent_identity.py # AgentIdentity, AgentSkill, AgentRole
│ │
│ ├── layer0_immutable_log/ # ── Layer 0: Append-Only Event Sourcing ──
│ │ ├── __init__.py
│ │ ├── log_writer.py # Append-only writer (JSONL format, never delete/edit)
│ │ ├── log_reader.py # Reader with filters (by time, author, project)
│ │ ├── log_indexer.py # Timestamp/author/project index (lightweight)
│ │ └── log_integrity.py # Hash chain verification (ensures no tampering)
│ │
│ ├── layer1_extraction/ # ── Layer 1: LLM Memory Extraction Engine ──
│ │ ├── __init__.py
│ │ ├── extractor.py # Main extraction orchestrator
│ │ ├── prompt_templates.py # Vietnamese structured prompts for Qwen
│ │ ├── type_classifier.py # Classify node type (issue/decision/assumption/enhancement/
│ │ │ # insight/contradiction/dependency/abstraction)
│ │ ├── importance_scorer.py # Score base_importance (0-1) from LLM output
│ │ ├── confidence_assessor.py # Assess confidence_score (0-1)
│ │ ├── tag_extractor.py # Extract context_tags automatically
│ │ ├── relation_detector.py # Detect parent/related relationships between nodes
│ │ ├── node_factory.py # Factory: creates MemoryNode from extraction results
│ │ └── batch_processor.py # Batch extraction for many log entries
│ │
│ ├── layer2_lifecycle/ # ── Layer 2: Memory Status Lifecycle ──
│ │ ├── __init__.py
│ │ ├── state_machine.py # Status state machine (7 states, valid transitions)
│ │ ├── triggers.py # Transition trigger conditions:
│ │ │ # - human_confirmation
│ │ │ # - usage_threshold
│ │ │ # - contradiction_detection
│ │ │ # - time_decay
│ │ ├── transition_logger.py # Log ALL status transitions (audit trail)
│ │ ├── promotion_engine.py # Short Memory → Long Memory promotion logic
│ │ ├── memory_category_manager.py # Manage Short/Long/Synthesized categories
│ │ └── evolution_tracker.py # Track version history khi node evolved
│ │
│ ├── layer3_ranking/ # ── Layer 3: Dynamic Influence Weight ──
│ │ ├── __init__.py
│ │ ├── weight_calculator.py # Main effective_weight formula
│ │ ├── recency_factor.py # recency_decay_factor(last_activated, now)
│ │ ├── usage_factor.py # usage_factor(usage_count) - logarithmic scaling
│ │ ├── context_match_scorer.py # context_match_score(node, current_context)
│ │ ├── reinforcement_scorer.py # reinforcement_score from success/failure feedback
│ │ ├── contradiction_penalty.py # contradiction_penalty(contradiction_refs)
│ │ ├── virtual_dom.py # ★ VIRTUAL DOM: Incremental View Maintenance
│ │ │ # - Local propagation only (not full recalc)
│ │ │ # - Change at branch → push updates to parent/child in branch only
│ │ │ # - Dirty flag + batch recalc
│ │ ├── ranking_cache.py # In-memory cache for frequently accessed weights
│ │ └── infinity_weight.py # Human-Validated infinity weight lock mechanism
│ │
│ ├── layer4_decay_rebase/ # ── Layer 4: Decay & Rebase Engine ──
│ │ ├── __init__.py
│ │ │
│ │ ├── decay/ # ─ Decay Subsystem ─
│ │ │ ├── __init__.py
│ │ │ ├── decay_engine.py # Main decay orchestrator
│ │ │ ├── activation_decay.py # Decay by: no activation in X time
│ │ │ ├── context_mismatch.py # Decay by: context mismatch (phase changed)
│ │ │ ├── override_decay.py # Decay by: overridden nhiều lần
│ │ │ ├── cognitive_fossil.py # ★ COGNITIVE FOSSIL Manager
│ │ │ │ # - Mark old nodes as "fossils"
│ │ │ │ # - No re-index when new hash rules learned
│ │ │ │ # - Natural sinking via Decay
│ │ │ └── decay_scheduler.py # Periodic decay scan scheduler
│ │ │
│ │ └── rebase/ # ─ Rebase Subsystem ─
│ │ ├── __init__.py
│ │ ├── rebase_engine.py # Main rebase orchestrator
│ │ ├── coactivation_detector.py # Detect: 2 nodes frequently activate together
│ │ ├── override_detector.py # Detect: 1 node repeatedly overrides another
│ │ ├── abstraction_builder.py # Create new Abstraction Node from rebase
│ │ ├── history_linker.py # Link abstraction back to source nodes (never delete)
│ │ └── human_rebase_handler.py # Handle human-confirmed conflict resolution rebase
│ │
│ ├── layer5_context_resolver/ # ── Layer 5: Context-Aware Node Selection ──
│ │ ├── __init__.py
│ │ ├── resolver.py # Main resolver orchestrator
│ │ ├── phase_matcher.py # Match by current project phase
│ │ ├── task_matcher.py # Match by active task
│ │ ├── dependency_walker.py # Walk dependency graph for related nodes
│ │ ├── tag_matcher.py # Match by context_tags intersection
│ │ ├── fingerprint_matcher.py # Match by semantic_fingerprint (LSH similarity)
│ │ ├── threshold_filter.py # Only pass nodes above context_match_threshold
│ │ └── conflict_filter.py # Exclude unresolved contradiction nodes from reasoning
│ │
│ ├── layer6_synthesis/ # ── Layer 6: Meta-Knowledge Synthesis Engine ──
│ │ ├── __init__.py
│ │ ├── synthesis_scanner.py # Periodic scan orchestrator
│ │ ├── redundancy_detector.py # Detect duplicate/near-duplicate nodes (LSH)
│ │ ├── pattern_clusterer.py # Cluster nodes by semantic pattern
│ │ ├── abstraction_suggester.py # Suggest new abstraction nodes
│ │ ├── rebase_suggester.py # Suggest rebases based on patterns
│ │ ├── promotion_suggester.py # Suggest Short → Long memory promotion
│ │ ├── suggestion_queue.py # Queue suggestions for human review
│ │ └── synthesis_scheduler.py # APScheduler periodic job
│ │
│ └── semantic/ # ── Semantic Intelligence Layer ──
│ ├── __init__.py
│ │
│ ├── embedding/ # ─ Dense Embedding Subsystem ─
│ │ ├── __init__.py
│ │ ├── embedding_engine.py # Load & run all-MiniLM-L6-v2
│ │ ├── embedding_cache.py # Cache embeddings to avoid recomputation
│ │ └── similarity_scorer.py # Cosine similarity between embeddings
│ │
│ ├── hashing/ # ─ Semantic Hashing Subsystem ─
│ │ ├── __init__.py
│ │ ├── lsh_hasher.py # MinHash LSH fingerprint generation
│ │ ├── fingerprint_manager.py # Store, retrieve, compare fingerprints
│ │ └── lsh_index.py # MinHashLSH index for fast similarity queries
│ │
│ └── learned_hashing/ # ─ ★ Dynamic Semantic Layer & Learned Hashing ─
│ ├── __init__.py
│ ├── alias_mapping.py # Contextual Dictionary / Alias Mapping
│ │ # - "ko" → "không", "sv" → "sinh viên" (informal abbreviations)
│ │ # - Self-learned conventions
│ ├── alias_learner.py # ★ Auto-learn new aliases from usage patterns
│ │ # - When Rebase merges "ko" and "không" →
│ │ # add alias rule automatically
│ ├── alias_store.py # Persistent storage for learned aliases
│ └── backward_compat.py # ★ COGNITIVE EVOLUTION: Backward Compatibility
│ # - Don't re-index old nodes on new rules
│ # - Old nodes = cognitive fossils
│ # - New Abstraction nodes take precedence naturally
│
├── store/ # ═══ STORAGE INFRASTRUCTURE ═══
│ ├── __init__.py
│ │
│ ├── micro_store/ # ── Micro Store (Per-Project) ──
│ │ ├── __init__.py
│ │ ├── micro_store.py # Main store wrapper (mount/unmount per project)
│ │ ├── node_dao.py # MemoryNode CRUD operations
│ │ ├── edge_dao.py # DAG Edge CRUD (parent, related, contradiction, pointer)
│ │ ├── dag_operations.py # DAG-specific: ancestors, descendants, cycle check
│ │ ├── query_engine.py # Complex queries: by status, tags, weight, time range
│ │ ├── schema_migrations.py # SQLite schema versioning & migrations
│ │ └── store_factory.py # Create new project store with full schema
│ │
│ ├── tiered_storage/ # ── ★ Tiered Storage (Hot/Warm/Cold) ──
│ │ ├── __init__.py
│ │ ├── tier_manager.py # Orchestrate data movement between tiers
│ │ ├── hot_tier.py # In-Memory/RAM: active, validated, draft nodes
│ │ │ # → Participates in Virtual DOM
│ │ ├── warm_tier.py # Local SQLite: resolved, recently demoted nodes
│ │ ├── cold_tier.py # Archive: deprecated/archived → Parquet/JSONL
│ │ │ # → "Cognitive fossils", no RAM cost, no index cost
│ │ │ # → Still retrievable by human request
│ │ ├── tier_policy.py # Rules for when to move between tiers
│ │ └── cold_archive_reader.py # Read back from Parquet/JSONL cold storage
│ │
│ ├── global_store/ # ── Global Tree Store (Shared Knowledge) ──
│ │ ├── __init__.py
│ │ ├── global_store.py # Main Global Tree SQLite store
│ │ ├── global_node_dao.py # CRUD for GlobalNodes (Synthesized/Super-Abstraction only)
│ │ ├── global_edge_dao.py # Edges in Global Tree
│ │ └── global_query.py # Query Global Tree by hash, tags, weight
│ │
│ └── sync/ # ── ★ Shared Tree Protocol (Git for Cognitive Memory) ──
│ ├── __init__.py
│ ├── sync_protocol.py # Main sync orchestrator
│ ├── merkle_tree.py # ★ Merkle Tree hash chain for sync verification
│ ├── push_handler.py # Agent pushes Abstraction Node → Global Tree
│ │ # - Only abstractions, NEVER raw data
│ │ # - Federated Memory principle
│ ├── fetch_handler.py # Agent fetches new Global nodes
│ │ # - Compare hashes, only get new ones
│ ├── pointer_linker.py # Create pointer from Local Tree → Global node
│ │ # - No copy, just reference link
│ ├── broadcast_handler.py # ★ Down-sync: Meta-Agent broadcasts patterns
│ │ # - Auto-create [Global_Pattern] tagged nodes in Local Trees
│ └── portability.py # ★ "Brain Sharing": zip/export Micro Store
│ # - Portable state as physical file
│ # - Transfer cognitive memory between agents
│
├── conflict/ # ═══ CONFLICT DETECTION & RESOLUTION ═══
│ ├── __init__.py
│ ├── conflict_detector.py # Detect: contradictory decisions, inconsistent assumptions
│ ├── override_tracker.py # Track override patterns (A overrides B how many times)
│ ├── conflict_node_factory.py # Create ConflictNode (don't fix, just record)
│ ├── contradiction_linker.py # Link contradiction_refs between nodes
│ └── resolution_flow.py # Resolution flow → human confirmation required
│
├── agents/ # ═══ MULTI-AGENT SYSTEM (HIVE MIND) ═══
│ ├── __init__.py
│ │
│ ├── foundation/ # ── Agent Foundation ──
│ │ ├── __init__.py
│ │ ├── base_agent.py # Base CognitiveAgent class
│ │ │ # - agent_id, skill_type, model_ref, store_ref
│ │ │ # - think(), observe(), decide()
│ │ ├── agent_identity.py # Agent identity management (name, role, skill)
│ │ ├── model_manager.py # Load/unload Qwen models on demand
│ │ │ # - 4-bit quantized for 3050Ti
│ │ │ # - Shared model instances across agents
│ │ └── agent_registry.py # Registry of all active agents
│ │
│ ├── micro_agent/ # ── Micro Agent (1 Agent = 1 Project) ──
│ │ ├── __init__.py
│ │ ├── micro_agent.py # Main Micro Agent class
│ │ │ # - Mount 1 Micro Store
│ │ │ # - "Blind" to outside, deep internal context
│ │ ├── reasoning_pipeline.py # Pipeline: Context Resolver → Ranking → Conflict Filter
│ │ │ # → Reasoning → Record activation → Update usage
│ │ ├── node_pusher.py # Push qualified Abstraction Nodes → Global Tree
│ │ │ # - NEVER push raw data
│ │ │ # - Only Synthesized Memory Nodes
│ │ ├── pattern_fetcher.py # Fetch from Global Tree → create [Global_Pattern] nodes
│ │ └── success_reporter.py # Report success/failure → feeds reinforcement_score
│ │
│ ├── meta_agent/ # ── Meta Agent (The Smartest — Global Tree Maintainer) ──
│ │ ├── __init__.py
│ │ ├── meta_agent.py # Main Meta Agent class
│ │ │ # - Does NOT read Raw Log
│ │ │ # - Only scans Global Tree nodes
│ │ │ # - Single purpose: maintain Global Tree
│ │ ├── global_tree_scanner.py # Scan for similar hash branches (LSH)
│ │ │ # - Cross-project pattern discovery
│ │ ├── super_abstraction.py # Create Super-Abstraction from merge
│ │ │ # - "In case X use branch A, in case Y use branch B"
│ │ ├── global_rebase_engine.py # ★ Global Rebase for deep conflicts
│ │ │
│ │ └── consensus/ # ── ★ Global Consensus Engine ──
│ │ ├── __init__.py
│ │ ├── consensus_engine.py # Orchestrate 3 consensus pillars
│ │ ├── adoption_ranker.py # ★ Pillar 1: Adoption-based Ranking (PageRank-like)
│ │ │ # - Track: activation_count + success_rate across agents
│ │ │ # - "Truth belongs to empirically proven majority"
│ │ ├── contextual_forker.py # ★ Pillar 2: Contextual Forking
│ │ │ # - Both A and B can be right in different contexts
│ │ │ # - Analyze context_tags of successful adopters
│ │ │ # - Auto-insert conditional ranking rules
│ │ └── meta_rebaser.py # ★ Pillar 3: Meta-Rebase
│ │ # - Deep conflicts → create encompassing rule node
│ │
│ ├── immune/ # ── ★ Adversarial Immune System ──
│ │ ├── __init__.py
│ │ ├── immune_base.py # Base immune agent (specialized skill)
│ │ │
│ │ ├── specialists/ # ─ Role-based Specialist Agents ─
│ │ │ ├── __init__.py
│ │ │ ├── logic_agent.py # Agent Logic: find logical holes, circular reasoning
│ │ │ ├── security_agent.py # Agent Security: detect risky decisions, vulnerabilities
│ │ │ └── optimizer_agent.py # Agent Optimizer: find redundancy, bloat
│ │ │
│ │ ├── quarantine/ # ─ Quarantine System ─
│ │ │ ├── __init__.py
│ │ │ ├── quarantine_manager.py # New Global nodes → Quarantine/Draft status first
│ │ │ │ # - NOT applied system-wide immediately
│ │ │ └── quarantine_policy.py # Rules for quarantine duration, review requirements
│ │ │
│ │ ├── cross_examination/ # ─ ★ Cross-Examination (Peer Review) ─
│ │ │ ├── __init__.py
│ │ │ ├── examiner.py # Download quarantined node → apply skill → find edge cases
│ │ │ ├── examination_scheduler.py # Schedule which agents review which nodes
│ │ │ └── verdict_collector.py # Collect verdicts from specialist agents
│ │ │
│ │ └── deprecation/ # ─ ★ Forceful Deprecation ─
│ │ ├── __init__.py
│ │ ├── deprecation_engine.py # Attach Contradiction Node directly → slam ranking
│ │ │ # - Multiple contradictions → ranking goes negative
│ │ │ # - Auto-deprecate before poison spreads
│ │ └── cascade_handler.py # Handle cascade effects of forceful deprecation
│ │
│ ├── sentinel/ # ── ★ Sentinel Agent (The Court Secretary) ──
│ │ ├── __init__.py
│ │ ├── sentinel_agent.py # Main Sentinel Agent class
│ │ │ # - READ-ONLY access (absolute safety)
│ │ │ # - Stands outside swarm debates (100% objective)
│ │ │
│ │ ├── threshold_monitors/ # ─ Threshold Trigger System ─
│ │ │ ├── __init__.py
│ │ │ ├── deadlock_monitor.py # Deadlock Threshold: Contradiction count == Validation count
│ │ │ │ # → Infinite argument loop detected
│ │ │ ├── impact_monitor.py # Impact Threshold: Node would change dozens of Micro-Stores
│ │ │ │ # → Strategic decision, needs human
│ │ │ └── confidence_monitor.py # Confidence Collapse: Meta-Agent confidence < threshold
│ │ │ # → System unsure, escalate
│ │ │
│ │ ├── ticket_generator.py # ★ Generate Human-Review Ticket (structured report)
│ │ │ # - Disputed Node content
│ │ │ # - Origin: which Project, which Micro-Agent
│ │ │ # - Argument A: proposer's reasoning
│ │ │ # - Argument B: immune agent's objection
│ │ │ # - Impact Analysis: expected effects if approved
│ │ └── impact_analyzer.py # Analyze cascading impact of node approval/rejection
│ │
│ └── runtime/ # ── Agent Orchestrator / Runtime ──
│ ├── __init__.py
│ ├── orchestrator.py # Main agent lifecycle manager
│ │ # - Start/stop agents
│ │ # - Mount/unmount Micro Stores
│ ├── scheduler.py # Schedule agent tasks, periodic jobs
│ ├── event_bus.py # Internal event system (no prompt-based chat!)
│ │ # - Events: NODE_PUSHED, CONFLICT_DETECTED, etc.
│ └── resource_manager.py # GPU VRAM management for 3050Ti
│ # - Load/unload models on demand
│ # - Never exceed 4GB VRAM
│
├── human_loop/ # ═══ HUMAN-IN-THE-LOOP SYSTEM ═══
│ ├── __init__.py
│ ├── review_queue.py # Queue management for pending reviews
│ │
│ ├── actions/ # ── ★ Human Override Actions (Absolute Weight) ──
│ │ ├── __init__.py
│ │ ├── approve_action.py # Approve → Human-Validated label
│ │ │ # → Lock rank at Infinity Weight
│ │ │ # → Deprecate ALL opposing Contradiction Nodes
│ │ │ # → All Micro-Agents auto-comply
│ │ ├── reject_action.py # Reject → archived/deprecated
│ │ │ # → Create Experience Node (lesson learned)
│ │ │ # → Agents learn to avoid same mistake
│ │ ├── merge_action.py # Merge/Rebase → Human writes new Abstraction Node
│ │ │ # → Resolves conflict manually
│ │ ├── ranking_override.py # Human adjusts ranking directly
│ │ ├── status_override.py # Human changes status directly
│ │ └── relation_override.py # Human modifies relations between nodes
│ │
│ ├── proposal_engine.py # Agent proposes: promotion, rebase, conflict resolution, decay
│ ├── decision_logger.py # Immutable log of ALL human decisions
│ ├── experience_factory.py # Create Experience Nodes from rejections
│ │ # → "Vaccine" against future mistakes
│ └── notification.py # Notify human of pending reviews (WebSocket)
│
├── memory/ # ═══ MEMORY MANAGEMENT ═══
│ ├── __init__.py
│ ├── short_memory.py # Short Memory: short-term reasoning, easy decay, promotable
│ ├── long_memory.py # Long Memory: stable, long-term influence, soft decay
│ ├── synthesized_memory.py # Synthesized Memory: higher abstraction, doesn't replace originals
│ ├── memory_classifier.py # Classify which category a node belongs to
│ ├── explosion_control.py # ★ Memory Explosion Prevention
│ │ # - Redundancy detection (LSH similarity > threshold)
│ │ # - Similarity clustering
│ │ # - Rebase suggestion
│ │ # - Abstraction promotion
│ │ # - NEVER delete, but keep system finite
│ └── cross_project.py # ★ Cross-Project Knowledge (Optional Advanced)
│ # - Global abstraction nodes
│ # - Project context overrides global
│ # - Prevent cross-project contamination
│
├── api/ # ═══ REST API ═══
│ ├── __init__.py
│ ├── app.py # FastAPI app factory
│ ├── routes/
│ │ ├── __init__.py
│ │ ├── project_routes.py # CRUD projects, interact, get memory
│ │ ├── node_routes.py # Node details, manual CRUD, status changes
│ │ ├── graph_routes.py # Graph data for visualization
│ │ ├── review_routes.py # Review queue, human actions
│ │ ├── agent_routes.py # Agent status, control
│ │ ├── global_routes.py # Global Tree exploration
│ │ └── analytics_routes.py # Heatmaps, timelines, statistics
│ ├── websocket_handler.py # Real-time updates to frontend
│ └── middleware.py # CORS, error handling, request logging
│
├── frontend/ # ═══ ELECTRON + REACT FRONTEND ═══
│ ├── package.json
│ ├── vite.config.ts
│ ├── electron/ # ── Electron Main Process ──
│ │ ├── main.ts
│ │ └── preload.ts
│ ├── src/ # ── React Renderer Process ──
│ │ ├── App.tsx
│ │ ├── main.tsx
│ │ ├── index.css # Tailwind directives & CSS variables
│ │ │
│ │ ├── components/
│ │ │ ├── KnowledgeGraph.tsx # Interactive DAG visualization
│ │ │ ├── NodeDetail.tsx # Detailed node view with all metadata
│ │ │ ├── InfluenceHeatmap.tsx # Node influence weight heatmap
│ │ │ ├── EvolutionTimeline.tsx # Memory evolution history timeline
│ │ │ ├── ConflictGraph.tsx # Conflict/contradiction visualization
│ │ │ ├── RebaseHistory.tsx # Rebase history tree view
│ │ │ ├── ReviewQueue.tsx # Human review queue with action buttons
│ │ │ ├── ReviewTicket.tsx # Detailed review ticket (A vs B arguments)
│ │ │ ├── AgentMonitor.tsx # Agent status dashboard
│ │ │ ├── GlobalTreeView.tsx # Global Tree exploration
│ │ │ ├── ProjectSelector.tsx # Project selection & creation
│ │ │ ├── InteractionPanel.tsx # Chat/interact with project agent
│ │ │ ├── TierViewer.tsx # Hot/Warm/Cold storage visualization
│ │ │ └── SynthesisSuggestions.tsx # Suggestions from Layer 6 for review
│ │ │
│ │ ├── pages/
│ │ │ ├── Dashboard.tsx # Main dashboard
│ │ │ ├── ProjectView.tsx # Single project deep view
│ │ │ ├── GlobalView.tsx # Global Tree + agent ecosystem
│ │ │ └── ReviewCenter.tsx # Human review center
│ │ │
│ │ ├── hooks/
│ │ │ ├── useSocket.ts # Socket.io connection hook
│ │ │ ├── useGraph.ts # Graph data management via TanStack Query
│ │ │ └── useReview.ts # Review queue state via TanStack Query
│ │ │
│ │ └── services/
│ │ ├── api.ts # API client (Axios/Fetch)
│ │ └── socket.ts # Socket.io client configuration
│ │
│ └── public/
│
├── tests/ # ═══ TESTS ═══
│ ├── unit/
│ │ ├── test_schema.py
│ │ ├── test_layer0_log.py
│ │ ├── test_layer1_extraction.py
│ │ ├── test_layer2_lifecycle.py
│ │ ├── test_layer3_ranking.py
│ │ ├── test_layer3_virtual_dom.py
│ │ ├── test_layer4_decay.py
│ │ ├── test_layer4_rebase.py
│ │ ├── test_layer5_resolver.py
│ │ ├── test_layer6_synthesis.py
│ │ ├── test_lsh_engine.py
│ │ ├── test_learned_hashing.py
│ │ ├── test_conflict_detection.py
│ │ ├── test_micro_store.py
│ │ ├── test_tiered_storage.py
│ │ ├── test_global_store.py
│ │ ├── test_sync_protocol.py
│ │ ├── test_merkle_tree.py
│ │ └── test_human_actions.py
│ │
│ ├── agent/
│ │ ├── test_micro_agent.py
│ │ ├── test_meta_agent.py
│ │ ├── test_immune_agents.py
│ │ ├── test_sentinel_agent.py
│ │ ├── test_consensus_engine.py
│ │ ├── test_cross_examination.py
│ │ └── test_quarantine.py
│ │
│ └── integration/
│ ├── test_full_pipeline.py # Conversation → Extract → Graph → Reasoning
│ ├── test_multi_agent_flow.py # Multiple agents interact via Global Tree
│ ├── test_immune_flow.py # Poisoned node → Immune detect → Deprecate
│ ├── test_sentinel_escalation.py # Deadlock → Sentinel → Human → Resolve
│ └── test_evolution_cycle.py # Full evolution: create → conflict → rebase → consensus
│
└── data/ # ═══ RUNTIME DATA ═══
├── projects/ # Micro Store files (project_xxx.db)
├── global/ # Global Tree (global_tree.db)
├── logs/ # Layer 0 immutable logs (*.jsonl)
├── cold/ # Cold tier archives (*.parquet, *.jsonl)
├── aliases/ # Learned alias mappings
└── models/ # Cached model weights
This repository contains a broad implementation surface for a memory-first multi-agent system, including benchmark tooling, API routes, runtime orchestration, and frontend scaffolding.
- Keep changes scoped and testable.
- Preserve public contracts unless migration notes are included.
- Add or update tests for behavior changes where possible.
Add your preferred license file (for example, MIT) before publishing publicly.