Refactor incremental planning, enhance observability, and improve project memory management

- Removed redundant state.objective assignment in IncrementalPlanner.
- Updated Replanner to correctly reflect step statuses and objectives.
- Integrated observability report rendering in Reporter class.
- Enhanced AgentState to conditionally add timeline events based on observability settings.
- Added graph impact recording in ApplyPatchTool and SearchReplaceTool.
- Implemented tests for incremental planning, observability, project memory, and repository graph functionalities.
- Improved error handling and logging for graph impact analysis.

Author: RIDAM7

.env.example

@@ -156,6 +156,24 @@ REPLAN_ON_FAILURE=true
 # against the leash with its own stop reason). 0 disables the cap.
 MAX_REPLANS=3
 
+# --- Project Memory (Phase 12, local, human-readable) ------------------------
+# Maintains local markdown memory under the workspace and injects useful entries
+# into future planning. No embeddings, cloud calls, or external database.
+PROJECT_MEMORY_ENABLED=true
+PROJECT_MEMORY_DIR=.localcli/memory
+
+# --- Repository Graph (Phase 13 MVP, local) ----------------------------------
+# Builds .localcli/graph.json with import/module edges and impact queries for
+# Python and JS/TS. Enhancement items such as call graph and export are not part
+# of the MVP.
+REPO_GRAPH_ENABLED=true
+GRAPH_DIR=.localcli
+
+# --- Observability (Phase 14, AgentState-backed) -----------------------------
+# Collect lightweight timeline events and render the run dashboard/report panels.
+OBSERVABILITY_ENABLED=true
+VERBOSITY=normal   # quiet | normal | verbose
+
 # --- LLM retries -------------------------------------------------------------
 # Structured-output retry/repair attempts per LLM call (all providers).
 MAX_RETRIES=3

agent/cli.py

@@ -30,7 +30,9 @@
 
 # Subcommands argparse owns; anything else as the first token is treated as a
 # bare-task shorthand for `run`.
-KNOWN_SUBCOMMANDS = {"run", "config", "models", "index", "search", "symbols", "context"}
+KNOWN_SUBCOMMANDS = {
+    "run", "config", "models", "index", "search", "symbols", "context", "memory", "graph",
+}
 
 
 # --- Routing table -----------------------------------------------------------
@@ -152,18 +154,21 @@ async def cmd_run(args):
     if mode == "agent":
         from agent.state.agent_state import AgentState, TaskMetadata
         from agent.context import build_context_bundle
+        from agent.memory.project_memory import ProjectMemoryManager
         state = AgentState(user_request=task_description,
                            task=TaskMetadata(description=task_description))
         try:
             state.loaded_context = await build_context_bundle(settings.get_workspace_path())
         except Exception:
             pass
+        project_memory = ProjectMemoryManager(settings.get_workspace_path())
+        project_memory.load_into_state(state)
         if caps:
             state.capabilities = caps.model_dump()
         # Phase 11: incremental planning is on by default (settings); the agent
         # loop then runs plan -> execute step -> observe -> replan.
         engine = build_engine("agent", safety_mode=safety_mode,
-                              memory_manager=orchestrator.memory_manager,
+                              memory_manager=project_memory,
                               incremental=settings.incremental_planning)
         state = await engine.execute(state)
         print(f"\nAgent run complete: status={state.final_outputs.status}, "
@@ -173,6 +178,10 @@ async def cmd_run(args):
         if settings.incremental_planning and state.plan.revisions:
             from agent.planning import render_plan_evolution
             print("\n" + render_plan_evolution(state))
+        project_memory.update_from_state(state)
+        if settings.observability_enabled and (args.observe or settings.verbosity == "verbose"):
+            from agent.observability import render_dashboard
+            print("\n" + render_dashboard(state))
         return 0
 
     # Phase 11: pipeline strategy with step-wise execution + replanning when
@@ -183,6 +192,11 @@ async def cmd_run(args):
     else:
         report_path = await orchestrator.run(task_description)
     print(f"\nExecution complete. Report generated at: {report_path}")
+    if settings.observability_enabled and (args.observe or settings.verbosity == "verbose"):
+        state = getattr(orchestrator, "last_state", None)
+        if state is not None:
+            from agent.observability import render_dashboard
+            print("\n" + render_dashboard(state))
     return 0
 
 
@@ -244,6 +258,49 @@ async def cmd_context(args):
     return 0
 
 
+def cmd_memory(args):
+    """Phase 12: view local project-memory markdown files."""
+    from agent.memory.project_memory import ProjectMemoryManager
+
+    manager = ProjectMemoryManager(settings.get_workspace_path())
+    if not manager.enabled:
+        print("Project memory is disabled (PROJECT_MEMORY_ENABLED=false).")
+        return 0
+    bundle = manager.load()
+    print(f"Project Memory: {manager.relative_dir}")
+    if not bundle.files:
+        print("(no project memory files)")
+        return 0
+    for rel in sorted(bundle.files):
+        print("\n" + "=" * 52)
+        print(rel)
+        print("-" * 52)
+        print(bundle.files[rel].rstrip())
+    if bundle.recovered_files:
+        print("\nRecovered/normalized:")
+        for rel in bundle.recovered_files:
+            print(f"- {rel}")
+    return 0
+
+
+def cmd_graph(args):
+    """Phase 13: repository graph impact query."""
+    if getattr(args, "graph_action", None) != "impact":
+        print("Usage: localcli graph impact <file>")
+        return 2
+    from agent.graph import GraphBuilder, ImpactAnalyzer
+
+    if not settings.repo_graph_enabled:
+        print("Repository graph is disabled (REPO_GRAPH_ENABLED=false).")
+        return 0
+    graph = GraphBuilder(settings.get_workspace_path()).build(force=args.refresh)
+    dependents = ImpactAnalyzer(graph).dependents(args.file)
+    print(f"Impact for {args.file}: {len(dependents)} dependent file(s)")
+    for dep in dependents:
+        print(f"- {dep}")
+    return 0
+
+
 async def cmd_index(args):
     from agent.orchestrator import Orchestrator
     orchestrator = Orchestrator()
@@ -303,6 +360,7 @@ def build_parser():
     p_run = sub.add_parser("run", help="Run an end-to-end coding task")
     p_run.add_argument("task", nargs="*", help="The task description")
     p_run.add_argument("--reindex", action="store_true", help="Force full rebuild of the index first")
+    p_run.add_argument("--observe", action="store_true", help="Print the Phase 14 AgentState dashboard after the run")
     _add_safety_flags(p_run)
 
     p_index = sub.add_parser("index", help="Build/update the workspace index")
@@ -316,6 +374,14 @@ def build_parser():
     p_context = sub.add_parser("context", help="Generate/refresh the repository Context Bundle (Phase 9, local)")
     p_context.add_argument("--refresh", action="store_true", help="Force a full rescan, ignoring the cache")
 
+    sub.add_parser("memory", help="View local project memory markdown files (Phase 12)")
+
+    p_graph = sub.add_parser("graph", help="Repository graph queries (Phase 13 MVP)")
+    graph_sub = p_graph.add_subparsers(dest="graph_action")
+    p_impact = graph_sub.add_parser("impact", help="List files that depend on a file")
+    p_impact.add_argument("file", help="Repository-relative file path")
+    p_impact.add_argument("--refresh", action="store_true", help="Force graph regeneration first")
+
     p_config = sub.add_parser("config", help="Configuration utilities")
     config_sub = p_config.add_subparsers(dest="config_action")
     config_sub.add_parser("check", help="Run preflight and print the resolved routing table + health")
@@ -351,6 +417,10 @@ async def _dispatch(args):
         return await cmd_symbols(args)
     if args.subcommand == "context":
         return await cmd_context(args)
+    if args.subcommand == "memory":
+        return cmd_memory(args)
+    if args.subcommand == "graph":
+        return cmd_graph(args)
     # default: run
     return await cmd_run(args)
 

agent/config.py

@@ -128,6 +128,22 @@ class AgentSettings(BaseSettings):
     replan_on_failure: bool = True
     max_replans: int = 3
 
+    # Phase 12: Project Memory. Local, human-readable markdown files that are
+    # loaded at run start and updated only after successful runs. This is NOT
+    # vector memory: no embeddings, cloud calls, or external database.
+    project_memory_enabled: bool = True
+    project_memory_dir: str = ".localcli/memory"
+
+    # Phase 13: Repository Graph MVP. Local graph.json with import/module edges
+    # and impact queries for primary languages (py/js/ts). No call graph here.
+    repo_graph_enabled: bool = True
+    graph_dir: str = ".localcli"
+
+    # Phase 14: Observability. Timeline events live on AgentState and the
+    # dashboard/report are read-only renderers over that state.
+    observability_enabled: bool = True
+    verbosity: str = "normal"  # quiet | normal | verbose
+
     # Logging
     log_level: str = "DEBUG"
 

agent/context/engine.py

@@ -70,6 +70,30 @@ async def build(self, *, use_cache: bool = True, force: bool = False,
 
         logger.info("Context engine: building fresh context bundle.")
         scan = self.scanner.scan(self.workspace)
+        dependency_graph = scan.dependency_graph
+        repository_graph = {}
+        if settings.repo_graph_enabled:
+            try:
+                from agent.graph.builder import GraphBuilder
+                graph_builder = GraphBuilder(self.workspace, scanner=self.scanner)
+                cached_graph = graph_builder.store.load()
+                if cached_graph is not None and cached_graph.fingerprint == scan.fingerprint:
+                    graph = cached_graph
+                else:
+                    graph = graph_builder.build_from_scan(scan)
+                dependency_graph = dict(scan.dependency_graph)
+                dependency_graph.update({
+                    path: module.dependencies
+                    for path, module in graph.modules.items()
+                    if module.dependencies
+                })
+                repository_graph = {
+                    "path": str(graph_builder.store.path),
+                    "modules": len(graph.modules),
+                    "edges": len(graph.edges),
+                }
+            except Exception as e:
+                logger.warning(f"Context engine: repository graph unavailable, using scan map: {e}")
 
         tech_stack = detectors.detect_tech_stack(scan.manifests)
         frameworks = detectors.detect_frameworks(tech_stack)
@@ -87,7 +111,8 @@ async def build(self, *, use_cache: bool = True, force: bool = False,
             tech_stack=tech_stack,
             entry_points=entry_points,
             conventions=conventions,
-            dependency_graph=scan.dependency_graph,
+            dependency_graph=dependency_graph,
+            repository_graph=repository_graph,
             symbol_count=scan.symbol_count,
         )
 

agent/context/schemas.py

@@ -61,8 +61,10 @@ class ContextBundle(BaseModel):
     entry_points: List[EntryPoint] = Field(default_factory=list)
     conventions: Conventions = Field(default_factory=Conventions)
     dependency_graph: Dict[str, List[str]] = Field(default_factory=dict)
+    repository_graph: Dict[str, str | int] = Field(default_factory=dict)  # Phase 13 graph metadata
     architecture_summary: Optional[str] = None  # None when no LLM was available
     symbol_count: int = 0
+    project_memory: Dict[str, str] = Field(default_factory=dict)  # Phase 12 markdown memory
 
     def to_planner_block(self) -> str:
         """Render a compact, deterministic text block for the planner prompt.
@@ -84,6 +86,17 @@ def to_planner_block(self) -> str:
         if self.entry_points:
             eps = [f"{e.kind}:{e.target}" for e in self.entry_points[:8]]
             lines.append("- Entry points: " + ", ".join(eps))
+        if self.repository_graph:
+            modules = self.repository_graph.get("modules", 0)
+            edges = self.repository_graph.get("edges", 0)
+            lines.append(f"- Repository graph: {modules} modules, {edges} import edges")
+        if self.dependency_graph:
+            graph_bits = []
+            for source, deps in sorted(self.dependency_graph.items())[:8]:
+                if deps:
+                    graph_bits.append(f"{source} -> {', '.join(sorted(deps)[:4])}")
+            if graph_bits:
+                lines.append("- Import graph: " + " | ".join(graph_bits))
         conv = self.conventions
         if conv.primary_language or conv.test_layout or conv.lint_tools:
             bits = []
@@ -102,6 +115,18 @@ def to_planner_block(self) -> str:
             lines.append("- Architecture:")
             for ln in self.architecture_summary.strip().splitlines():
                 lines.append(f"    {ln}")
+        if self.project_memory:
+            lines.append("- Project Memory:")
+            for rel, text in sorted(self.project_memory.items()):
+                entries = []
+                for line in text.splitlines():
+                    stripped = line.strip()
+                    if stripped.startswith("- "):
+                        entries.append(stripped[2:])
+                if entries:
+                    lines.append(f"    {rel}:")
+                    for entry in entries[:8]:
+                        lines.append(f"      - {entry}")
         return "\n".join(lines)
 
 

agent/engine/agent_engine.py

@@ -18,7 +18,7 @@
 import asyncio
 import json
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import TYPE_CHECKING, Any, Dict, Optional
 
 from pydantic import BaseModel, Field
 
@@ -36,6 +36,9 @@
 from agent.validation import BuildValidator, LintValidator, TestValidator
 from agent.retrieval import RipgrepSearch, SymbolIndex, TreeSitterIndexer
 
+if TYPE_CHECKING:
+    from agent.planning import StepOutcome
+
 
 class AgentAction(BaseModel):
     """The structured action the policy model returns each turn."""

agent/graph/__init__.py

@@ -0,0 +1,19 @@
+"""Phase 13 - lightweight repository graph MVP."""
+
+from agent.graph.builder import GraphBuilder
+from agent.graph.impact_analyzer import ImpactAnalyzer
+from agent.graph.queries import build_or_load_graph, impact
+from agent.graph.schemas import GraphEdge, GraphModule, RepositoryGraph
+from agent.graph.store import GraphStore, resolve_graph_dir
+
+__all__ = [
+    "GraphBuilder",
+    "GraphEdge",
+    "GraphModule",
+    "GraphStore",
+    "ImpactAnalyzer",
+    "RepositoryGraph",
+    "build_or_load_graph",
+    "impact",
+    "resolve_graph_dir",
+]