docs: capture graph intelligence phase status and plan

Signed-off-by: phernandez <paul@basicmachines.co>
2026-06-21 13:47:35 +00:00 · 2026-03-05 10:00:49 -06:00
4 changed files with 1937 additions and 0 deletions
@@ -0,0 +1,594 @@
+# SPEC-LOCAL-GRAPH-INTELLIGENCE-IMPLEMENTATION-PLAN
+
+**Status:** Draft (Decision-Complete)  
+**Date:** 2026-03-05  
+**Owner:** Basic Memory Engineering  
+**Implementation Status (2026-03-05):** Phase 1 contract skeleton implemented in `basic-memory` branch `codex/graph-intelligence-phase1`.  
+**Related Specs:**
+1. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-MASTER.md`
+2. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-TECHNICAL-ADDENDUM.md`
+3. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE.md`
+
+## Scope and Intent
+
+This document is the execution handoff for Local+ Graph Intelligence.
+
+It defines exactly how we will deliver graph and FCM capabilities inside the existing Basic Memory architecture:
+1. FastAPI-first business logic.
+2. MCP and CLI as thin facades.
+3. Local/cloud contract parity.
+4. Tight build-test-iterate loop for fast delivery.
+
+This file is intentionally implementation-oriented and does not duplicate pricing narrative from the master spec.
+
+## Architecture Alignment (FastAPI-first, MCP/CLI facade)
+
+Locked architecture alignment for implementation:
+1. MCP tools remain thin proxy facades.
+2. CLI `bm tool` commands call MCP tools in JSON mode.
+3. Core logic lives in FastAPI routers and services.
+4. Cloud and local share the same REST contracts.
+5. Per-project routing continues through existing project client patterns.
+
+Execution mapping:
+1. API routers define public contracts in `/graph` and `/fcm` domains.
+2. Services own traversal, scoring, simulation, and fallback logic.
+3. Repositories and index providers own data access and graph index operations.
+4. MCP typed clients call REST endpoints and return JSON-first tool output.
+5. CLI passthrough executes tool calls and prints machine-friendly JSON.
+
+## Locked Decisions
+
+1. SQLite remains operational source for entities, relations, embeddings, and project state.
+2. Markdown remains source of truth.
+3. Oxigraph/pyoxigraph is the derived graph index for deep traversal.
+4. FCM simulation runs in Python service layer; it is not delegated to graph DB query engines.
+5. Graph index is rebuildable and disposable; stale index never blocks user workflows.
+6. FCM model and scenario artifacts persist in app database.
+7. Local+ features are gated by config flags first; entitlement wiring follows later.
+8. Graph-first vertical slices ship before deep FCM expansion.
+9. Atomic tools ship first; orchestration workflows are deferred.
+10. Existing `build_context` and `search_notes` remain backward compatible with no breaking change.
+
+## Progress Snapshot (as of 2026-03-05)
+
+Completed in Phase 1:
+1. Added `/graph` and `/fcm` v2 routers with all required contract endpoints.
+2. Added graph/FCM request and response schemas for all public API contracts.
+3. Added service-layer implementations for graph and FCM contract endpoints.
+4. Added typed MCP clients for graph and FCM API calls.
+5. Added MCP tools: `graph_lineage`, `graph_impact`, `graph_health`, `graph_reindex`, `fcm_simulate`, `fcm_rank_actions`, `fcm_import_model`, `fcm_export_model`.
+6. Added CLI passthrough commands under `bm tool ...` for all planned graph/FCM operations.
+7. Added scheduler task names for graph lifecycle: `sync_graph_entity`, `sync_graph_project`, `reindex_graph_project`.
+8. Added focused tests for API, MCP clients/tools, and CLI graph/FCM passthrough.
+9. Added fast-loop `just` targets: `test-graph-intel-api`, `test-graph-intel-mcp`, `test-graph-intel-cli`, `test-graph-intel`.
+
+Validation completed:
+1. `just test-graph-intel` passes.
+2. `ruff check` passes on changed files.
+3. `pyright` passes on changed files.
+
+Still pending after Phase 1:
+1. SQL-backed traversal/scoring for graph `lineage`, `impact`, and `health`.
+2. Oxigraph provider integration and stale-index catch-up flow.
+3. Persistent FCM model/scenario state and interop round-trip guarantees.
+4. Config-flag and entitlement gating at API/tool boundaries.
+5. Performance instrumentation and p95 envelope enforcement.
+
+## Delivery Phases
+
+### Phase 1: Contract skeleton
+
+Status: Completed (2026-03-05)
+
+Deliverables:
+1. Add `/graph` and `/fcm` API routers with request/response schemas.
+2. Add typed MCP clients for graph and FCM endpoints.
+3. Add MCP tool passthrough commands for all new operations.
+4. Add CLI `bm tool` passthrough commands mirroring MCP surface.
+5. Add minimal smoke tests for route reachability and schema validation.
+
+Exit criteria:
+1. All endpoints return structured success and error envelopes.
+2. MCP/CLI paths execute end-to-end with stubbed service responses.
+
+### Phase 2: Graph capabilities on SQL-backed logic
+
+Status: Next active phase
+
+Deliverables:
+1. Implement `lineage`, `impact`, and `health` in service layer using SQL-backed traversal and scoring.
+2. Add provenance/evidence linking in graph outputs.
+3. Add deterministic graph-health calculations for fixed snapshots.
+
+Exit criteria:
+1. `graph_lineage`, `graph_impact`, and `graph_health` pass contract tests.
+2. SQL fallback behavior is explicit and covered by tests.
+
+### Phase 3: Oxigraph derived index provider
+
+Status: Planned
+
+Deliverables:
+1. Introduce Oxigraph provider behind graph-query interface.
+2. Add lazy catch-up jobs and project-wide reindex operation.
+3. Preserve SQL fallback when index is missing or stale.
+
+Exit criteria:
+1. Stale index path serves results via SQL and schedules catch-up.
+2. Index rebuild can be triggered and completed without data loss.
+
+### Phase 4: FCM import/simulate/rank/export
+
+Status: Planned (contract endpoints complete, full behavior pending)
+
+Deliverables:
+1. Implement CSV-first import/export contracts.
+2. Implement deterministic simulation core with convergence metadata.
+3. Implement action ranking with evidence references and confidence output.
+4. Persist scenario inputs and result artifacts.
+
+Exit criteria:
+1. Research flow scenario passes: import -> simulate -> rank -> export.
+2. Interop round-trip preserves node/edge counts and signed weights.
+
+### Phase 5: Hardening
+
+Status: Planned
+
+Deliverables:
+1. Performance tuning against published latency envelopes.
+2. Local/cloud parity tests for semantics and error behavior.
+3. MCP prompt/docs updates for new graph and FCM tools.
+4. Operational docs for reindex, fallback, and troubleshooting.
+
+Exit criteria:
+1. `just check` passes before merge.
+2. Acceptance criteria in this document are fully met.
+
+## API and Interface Additions
+
+### Shared API conventions
+
+1. All endpoints are project-scoped under `/v2/projects/{project_id}`.
+2. Request and response bodies are JSON-first and agent-friendly.
+3. Success envelope is endpoint-specific payload with deterministic fields and optional probabilistic fields.
+4. Error envelope:
+```json
+{
+  "error": {
+    "code": "INVALID_ARGUMENT|NOT_FOUND|INDEX_NOT_READY|MODEL_INVALID|RESOURCE_LIMIT_EXCEEDED|INTERNAL_ERROR",
+    "message": "string",
+    "details": {}
+  }
+}
+```
+5. Latency and scale targets are p95 targets for local default hardware profile.
+
+### 1) `POST /v2/projects/{project_id}/graph/lineage`
+
+Purpose: explain decision lineage and supporting evidence paths.
+
+Request schema:
+```json
+{
+  "start": "string",
+  "goal": "string|null",
+  "max_hops": 4,
+  "relation_filters": ["string"]
+}
+```
+
+Response schema:
+```json
+{
+  "root": {"id": "string", "title": "string", "permalink": "string"},
+  "paths": [
+    {
+      "path_id": "string",
+      "nodes": [{"id": "string", "title": "string"}],
+      "edges": [{"relation": "string", "direction": "outgoing|incoming"}],
+      "deterministic_path_score": 0.0,
+      "confidence": 0.0,
+      "evidence_refs": ["memory://..."]
+    }
+  ],
+  "generated_at": "RFC3339"
+}
+```
+
+Deterministic fields: `root`, `paths.nodes`, `paths.edges`, `deterministic_path_score`, `generated_at`.  
+Probabilistic fields: `confidence`.  
+Latency target: p95 <= 450ms with `max_hops<=4`.  
+Scale envelope: up to 50k nodes and 300k edges.
+
+### 2) `POST /v2/projects/{project_id}/graph/impact`
+
+Purpose: preview impact radius before edits or decisions.
+
+Request schema:
+```json
+{
+  "target": "string",
+  "horizon": 2,
+  "relation_filters": ["string"],
+  "include_reasons": true
+}
+```
+
+Response schema:
+```json
+{
+  "target": {"id": "string", "title": "string"},
+  "affected": [
+    {
+      "id": "string",
+      "title": "string",
+      "distance": 1,
+      "impact_score": 0.0,
+      "confidence": 0.0,
+      "reasons": ["string"],
+      "evidence_refs": ["memory://..."]
+    }
+  ],
+  "summary": {"total_considered": 0, "total_returned": 0}
+}
+```
+
+Deterministic fields: membership, distance, summary counts.  
+Probabilistic fields: `impact_score`, `confidence`.  
+Latency target: p95 <= 650ms for `horizon<=3`.  
+Scale envelope: default 200 results, hard cap 1000 with pagination token.
+
+### 3) `GET /v2/projects/{project_id}/graph/health`
+
+Purpose: report deterministic graph quality and actionable issues.
+
+Query params:
+1. `scope` optional directory prefix.
+2. `timeframe` optional window like `30d`.
+
+Response schema:
+```json
+{
+  "metrics": {
+    "orphan_rate": 0.0,
+    "stale_central_nodes": 0,
+    "overloaded_hubs": 0,
+    "contradiction_candidates": 0
+  },
+  "issues": [
+    {
+      "issue_type": "orphan|stale_central|overloaded_hub|contradiction_candidate",
+      "entity_id": "string",
+      "severity": "low|medium|high",
+      "reason": "string",
+      "suggested_action": "string",
+      "confidence": 0.0
+    }
+  ],
+  "computed_at": "RFC3339"
+}
+```
+
+Deterministic fields: `metrics`, issue membership for fixed snapshot.  
+Probabilistic fields: contradiction confidence when applicable.  
+Latency target: p95 <= 1500ms project-wide, <= 700ms scoped.
+
+### 4) `POST /v2/projects/{project_id}/graph/reindex`
+
+Purpose: force project-wide graph index rebuild.
+
+Request schema:
+```json
+{
+  "mode": "full|incremental",
+  "reason": "string|null"
+}
+```
+
+Response schema:
+```json
+{
+  "job_id": "string",
+  "status": "queued|running|completed|failed",
+  "scheduled_at": "RFC3339"
+}
+```
+
+Deterministic fields: job metadata and status transitions.  
+Probabilistic fields: none.  
+Latency target: enqueue response p95 <= 120ms.
+
+### 5) `POST /v2/projects/{project_id}/fcm/simulate`
+
+Purpose: run FCM scenario simulation.
+
+Request schema:
+```json
+{
+  "actions": [{"node_id": "string", "delta": 0.2}],
+  "scenario": {
+    "steps": 12,
+    "activation": "tanh|sigmoid|bounded_linear",
+    "decay": 0.05
+  },
+  "clamp_rules": [{"node_id": "string", "min": -1.0, "max": 1.0}]
+}
+```
+
+Response schema:
+```json
+{
+  "baseline": [{"node_id": "string", "state": 0.0}],
+  "projected": [{"node_id": "string", "state": 0.0}],
+  "deltas": [{"node_id": "string", "delta": 0.0}],
+  "stability": {"converged": true, "iterations_used": 0, "residual": 0.0},
+  "confidence": 0.0,
+  "explanations": [{"node_id": "string", "top_influencers": [{"source": "string", "weight": 0.0}]}],
+  "evidence_refs": ["memory://..."]
+}
+```
+
+Deterministic fields: baseline, projected, deltas, stability for fixed model and params.  
+Probabilistic fields: confidence.  
+Latency target: p95 <= 1000ms for <=500 nodes and <=5000 edges.
+
+### 6) `POST /v2/projects/{project_id}/fcm/rank-actions`
+
+Purpose: rank candidate interventions by expected outcome and risk.
+
+Request schema:
+```json
+{
+  "goal": "string",
+  "constraints": {
+    "max_negative_impact": 0.25,
+    "required_tags": ["string"],
+    "disallowed_nodes": ["string"]
+  },
+  "top_k": 10
+}
+```
+
+Response schema:
+```json
+{
+  "goal": {"node_id": "string", "label": "string"},
+  "recommendations": [
+    {
+      "action_node_id": "string",
+      "expected_goal_delta": 0.0,
+      "risk_penalty": 0.0,
+      "net_score": 0.0,
+      "confidence": 0.0,
+      "rationale": ["string"],
+      "evidence_refs": ["memory://..."]
+    }
+  ]
+}
+```
+
+Deterministic fields: candidate set and constraint compliance.  
+Probabilistic fields: expected delta, penalty, net score, confidence.  
+Latency target: p95 <= 1500ms for top-10 from <=100 candidates.
+
+### 7) `POST /v2/projects/{project_id}/fcm/import`
+
+Purpose: import FCM model from CSV-first contract.
+
+Request schema:
+```json
+{
+  "source": "string",
+  "format": "csv_bundle_v1",
+  "merge_mode": "replace|upsert"
+}
+```
+
+Response schema:
+```json
+{
+  "import_id": "string",
+  "nodes_loaded": 0,
+  "edges_loaded": 0,
+  "warnings": ["string"],
+  "errors": ["string"]
+}
+```
+
+Deterministic fields: counts and validation diagnostics.  
+Probabilistic fields: none.  
+Latency target: p95 <= 2500ms for 10k edges import.
+
+### 8) `POST /v2/projects/{project_id}/fcm/export`
+
+Purpose: export FCM model for interoperability.
+
+Request schema:
+```json
+{
+  "format": "csv_bundle_v1",
+  "selection": {
+    "scope": "all|tag|subgraph",
+    "tag": "string|null",
+    "seed_nodes": ["string"]
+  }
+}
+```
+
+Response schema:
+```json
+{
+  "export_id": "string",
+  "format": "csv_bundle_v1",
+  "files": [{"name": "nodes.csv", "path": "string"}, {"name": "edges.csv", "path": "string"}],
+  "node_count": 0,
+  "edge_count": 0
+}
+```
+
+Deterministic fields: file names and counts for fixed selection.  
+Probabilistic fields: none.  
+Latency target: p95 <= 1800ms for 50k edges export.
+
+## Data Model and Storage Boundaries
+
+1. SQLite is mandatory operational source for entities, relations, embeddings, and project metadata.
+2. Oxigraph stores derived knowledge graph index only.
+3. FCM state persists in app database with scenario artifacts and run history.
+4. Graph index is rebuildable and disposable by design.
+5. Markdown files remain canonical source of truth.
+
+Implementation data boundaries:
+1. Knowledge graph schema tracks descriptive nodes and typed edges plus provenance.
+2. FCM schema tracks signed weighted causal edges and node states.
+3. Provenance model requires `evidence_refs`, `confidence`, and `updated_at`.
+4. Scenario model stores interventions, constraints, run parameters, and output deltas.
+5. Interop schema starts with CSV-first Mental Modeler contract.
+
+## Background Jobs and Index Lifecycle
+
+Scheduler tasks to add:
+1. `sync_graph_entity`
+2. `sync_graph_project`
+3. `reindex_graph_project`
+
+Lifecycle rules:
+1. Note writes, edits, moves, and deletes schedule graph-index sync tasks.
+2. Scheduling pattern mirrors existing vector sync behavior.
+3. On stale or missing graph index, request path serves via SQL fallback and schedules catch-up.
+4. Reindex is idempotent and safe to rerun.
+5. Index version metadata is tracked per project for staleness checks.
+
+Operational behaviors:
+1. Foreground requests never block on full reindex completion.
+2. Background job failures surface in health endpoints with actionable status.
+3. Reindex job can run incremental or full mode.
+4. Phase 1 note: scheduler task names and reindex enqueue path are implemented; write/edit/move/delete sync hooks still need explicit wiring.
+
+## MCP and CLI Surface
+
+New MCP tools:
+1. `graph_lineage`
+2. `graph_impact`
+3. `graph_health`
+4. `fcm_simulate`
+5. `fcm_rank_actions`
+6. `fcm_import_model`
+7. `fcm_export_model`
+
+CLI passthrough additions:
+1. `bm tool graph-lineage ...`
+2. `bm tool graph-impact ...`
+3. `bm tool graph-health ...`
+4. `bm tool fcm-simulate ...`
+5. `bm tool fcm-rank-actions ...`
+6. `bm tool fcm-import-model ...`
+7. `bm tool fcm-export-model ...`
+
+Output conventions:
+1. Default output is JSON for MCP and CLI.
+2. MCP supports optional `output_format="text"` for human-readable summaries.
+3. CLI remains JSON-first to keep agent integration deterministic.
+
+## Test Strategy (fast loop + gates)
+
+### Slice-by-slice loop
+
+For each vertical slice, implement in this order:
+1. API contract and schema.
+2. Typed MCP client.
+3. MCP tool passthrough.
+4. CLI passthrough.
+5. Focused tests for API/MCP/CLI.
+
+Fast checks per slice:
+1. Targeted `pytest` for changed API, MCP, and CLI modules.
+2. `just fast-check`.
+3. `just doctor`.
+4. `just test-graph-intel` for graph/FCM-only iteration loop.
+
+Milestone gates:
+1. SQLite unit and integration pass first.
+2. Selective Postgres parity tests for new graph and FCM contracts.
+3. Full `just check` before merge.
+
+### Required test cases and scenarios
+
+1. Casual user impact preview before note edit.
+2. Decision audit: lineage plus evidence references explain recommendation.
+3. Graph health deterministic output for fixed snapshot.
+4. Research flow: import model -> simulate -> rank -> export.
+5. Sparse and contradictory graph input degrades gracefully.
+6. Interop round-trip preserves node/edge counts and signed weights.
+7. Local and cloud parity on contract semantics and error model.
+8. Stale index fallback path returns valid response and schedules catch-up.
+
+## Rollout and Feature Flagging
+
+Rollout controls:
+1. Gate graph and FCM endpoints behind config flags first.
+2. Add entitlement enforcement after behavior and reliability stabilize.
+3. Keep existing tools and endpoints fully backward compatible.
+
+Suggested flags:
+1. `feature_graph_intelligence_enabled`
+2. `feature_fcm_enabled`
+3. `feature_graph_oxigraph_provider_enabled`
+4. `feature_graph_sql_fallback_enabled`
+
+Rollout sequence:
+1. Enable contract skeleton in dev.
+2. Enable graph features for internal alpha users.
+3. Enable Oxigraph provider with fallback-on by default.
+4. Enable FCM import/simulate/rank/export for research alpha users.
+5. Promote to Local+ beta when acceptance criteria are met.
+
+## Risks and Mitigations
+
+1. Risk: graph query complexity increases p95 latency.  
+Mitigation: strict query caps, fallback path, and performance budgets per endpoint.
+2. Risk: stale index produces confusing outputs.  
+Mitigation: explicit staleness checks, SQL fallback, and background catch-up scheduling.
+3. Risk: FCM recommendations appear opaque.  
+Mitigation: require evidence references, confidence fields, and deterministic simulation metadata.
+4. Risk: local/cloud contract drift.  
+Mitigation: shared schemas, contract tests, and parity checks in CI gates.
+5. Risk: integration surface grows faster than team can validate.  
+Mitigation: phase gates and vertical-slice completion before opening next phase.
+
+## Improvement Backlog (Post-Phase 1)
+
+1. Refactor `bm tool` graph/FCM commands into a dedicated CLI module to reduce `tool.py` size and improve maintainability.
+2. Consolidate repeated MCP text-formatting helpers for graph/FCM outputs.
+3. Replace deterministic placeholder graph behavior with SQL-backed lineage/impact/health implementations.
+4. Add explicit config/entitlement enforcement for graph/FCM endpoints and tools.
+5. Add performance telemetry and p95 reporting for graph and FCM routes.
+6. Add parity and degradation tests for stale-index fallback and contradictory/sparse inputs.
+
+## Acceptance Criteria
+
+1. All required sections in this document are complete with no unresolved decisions.
+2. API/interface contracts are implementation-ready with request, response, error, latency, and scale details.
+3. Architecture alignment is explicit: FastAPI logic core, MCP/CLI facades, shared local/cloud contracts.
+4. Delivery phases define concrete outputs and exit criteria.
+5. Test strategy includes tight iteration loop and milestone gates.
+6. Required scenario matrix is covered in test plan and mapped to implementation phases.
+7. Rollout plan includes feature flags and backward compatibility guarantees.
+8. An implementer can execute this plan without additional architecture clarification.
+
+## Assumptions and Defaults
+
+1. Config-flag gating first; entitlement wiring later.
+2. Graph-first vertical slices before deep FCM expansion.
+3. Atomic tools first; orchestration layer deferred.
+4. JSON-first contracts for agent usability.
+5. No breaking changes to existing `build_context` and `search_notes`.
+
+## Out of Scope
+
+1. Implementation details unrelated to graph/FCM delivery phases in this document.
+2. Migration execution.
+3. Pricing and positioning rewrites.
+4. Cloud infrastructure changes in this phase.
@@ -0,0 +1,782 @@
+# SPEC-LOCAL-GRAPH-INTELLIGENCE-MASTER: Local+ Graph Intelligence Blueprint
+
+**Status:** Draft (Iteration 2, Decision-Complete)  
+**Date:** 2026-03-05  
+**Owner:** Basic Memory  
+**Primary Audience:** Internal build team (Product, Engineering, GTM)  
+**Current Phase (2026-03-05):** Implementation Plan Phase 1 is complete; Phase 2 (SQL-backed graph logic) is the active engineering phase.  
+**Related Specs:**
+1. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE.md`
+2. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-TECHNICAL-ADDENDUM.md`
+3. `/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-IMPLEMENTATION-PLAN.md`
+
+Reading guide:
+1. Sections 1-5 define the business and product decisions.
+2. Sections 6-10 define architecture and interface contracts.
+3. Sections 11-14 define pricing, rollout, and decision gates for execution.
+
+## 1) Executive Thesis
+
+Basic Memory will ship **Local+ Graph Intelligence** as a premium local capability that upgrades the product from retrieval to decision support.
+
+Positioning statement:
+1. "Keep your local workflow. Add decision intelligence as complexity grows."
+2. The product sells safer decisions and explainable recommendations, not graph database mechanics.
+
+Locked thesis decisions:
+1. SQLite will remain the operational core.
+2. Markdown will remain source of truth.
+3. Graph and FCM indexes will be derived and rebuildable.
+4. Oxigraph/pyoxigraph will be the v1 graph index path.
+5. FCM simulation will run in a Python service layer.
+6. SurrealDB and FalkorDB will not be core dependencies in v1 due license-roadmap mismatch.
+7. Product messaging will sell outcomes (safer decisions, explainable recommendations), not database internals.
+
+## 2) Problem and Opportunity
+
+Current state after v0.19:
+1. Recursive SQL traversal can retrieve connected notes but becomes expensive and noisy after a few hops.
+2. Users still do manual synthesis for impact analysis, decision lineage, and contradiction resolution.
+3. Researchers need causal reasoning and scenario modeling, not only graph navigation.
+
+Opportunity:
+1. Deliver a premium local tier that materially improves decision quality while keeping data local.
+2. Create a bridge from knowledge graph navigation to causal simulation (FCM).
+3. Open a research-heavy market segment that values explainability and model interoperability.
+
+Business opportunity:
+1. Add a middle tier between free OSS and cloud subscription.
+2. Preserve an upgrade path to hosted collaboration for research teams later.
+3. Differentiate Basic Memory for research-grade workflows without forcing cloud adoption.
+
+## 3) User Segments and Jobs-to-be-Done
+
+| Segment | Primary Job-to-be-Done | Pain Today | Value Trigger |
+|---|---|---|---|
+| Casual local builder | Avoid breaking related notes when editing | Hidden dependencies and rework | Impact preview before edits |
+| Solo technical founder | Keep architecture and decision context coherent | Context overload and drift | Decision lineage + impact radius |
+| Research user | Model and test intervention strategies | No integrated causal simulation with notes | FCM simulation + action ranking |
+| Product/research lead | Synthesize evidence quickly across many docs | Fragmented understanding | Path exploration + priority briefs |
+
+## 4) Product Outcomes (not feature list)
+
+Local+ Graph Intelligence will optimize for these outcomes:
+1. **Change Safety:** users catch downstream impacts before they edit.
+2. **Decision Clarity:** users can explain why an answer or recommendation was produced.
+3. **Knowledge Health:** users keep larger graphs coherent with less manual audit work.
+4. **Research Leverage:** users run scenario-level reasoning tied to explicit evidence.
+
+Outcome metrics (for 30-day retained Local+ cohorts):
+1. Median time-to-understanding for complex topics decreases by at least 35% for active Local+ users.
+2. User-reported surprise side effects after note edits decrease by at least 30%.
+3. At least 60% of active Local+ users invoke graph intelligence features weekly.
+4. At least 40% of research-profile Local+ users invoke one FCM workflow weekly.
+
+## 5) Feature Set v1/v1.5/v2
+
+### v1 (post-v0.19 launch scope)
+
+Included:
+1. Decision Lineage
+2. Impact Radius
+3. Path Explorer (guided)
+4. Graph Health (orphans, stale-central nodes, overloaded hubs)
+5. CSV FCM import/export (nodes and edges)
+6. FCM simulation for explicit action scenarios
+7. FCM action ranking with evidence-linked rationale
+
+Excluded:
+1. Native Mental Modeler project format write support
+2. Team governance and shared model policy controls
+3. Cloud-only enhancements
+
+### v1.5
+
+Included:
+1. Contradiction Watch with reconciliation queue
+2. Priority Briefs (graph + FCM leverage summary)
+3. Stronger uncertainty propagation in FCM scoring
+4. Cloud execution optionality for heavy simulation jobs
+
+### v2
+
+Included:
+1. Team-shared model governance
+2. Hosted collaboration features for research teams
+3. Optional native model translators beyond CSV baseline
+
+Cut line policy:
+1. If a capability cannot meet explainability requirements, it moves to v1.5+.
+2. If a capability requires cloud to function, it cannot be marked v1.
+3. If a capability cannot meet local performance envelopes, it cannot be promoted into default workflows.
+
+## 6) Technical Architecture (Two-Graph Model)
+
+### High-level architecture
+
+```mermaid
+flowchart LR
+    A[Markdown Files Source of Truth] --> B[Parser + Sync Pipeline]
+    B --> C[SQLite Operational Store]
+    B --> D[Derived Knowledge Graph Index Oxigraph]
+    C --> E[Graph Intelligence Service]
+    D --> E
+    E --> F[Lineage Impact Path Health APIs]
+    C --> G[FCM Service Python]
+    D --> G
+    G --> H[Simulation Ranking Interop APIs]
+```
+
+### Two-graph model
+
+1. **Knowledge Graph (descriptive):** notes, decisions, concepts, and typed relations.
+2. **FCM Graph (causal):** signed weighted influence links between goals, drivers, risks, and interventions.
+
+### Core architectural decisions
+
+1. SQLite is authoritative for entities, observations, relations, metadata, embeddings, and project state.
+2. Oxigraph is a derived index for multi-hop graph traversal and graph-pattern retrieval.
+3. FCM calculations run in Python using explicit model state and deterministic numerical steps.
+4. Local mode runs fully offline.
+5. Cloud mode can execute the same contracts via adjunct services while Neon remains system of record.
+
+## 7) Backend Decision and Trade-Offs
+
+### Final recommendation
+
+Use this stack for v1:
+1. SQLite (existing): primary operational store.
+2. Oxigraph/pyoxigraph: derived knowledge graph index.
+3. Python FCM service: causal simulation and ranking.
+
+Decision rationale:
+1. This preserves local-first UX while enabling deeper traversal and causal simulation.
+2. This avoids restrictive licensing dependencies in the core product path.
+3. This keeps a clean cloud portability path where Neon remains the hosted system of record.
+
+### Trade-off matrix
+
+| Option | Strengths | Risks | Decision |
+|---|---|---|---|
+| SQLite + Oxigraph + Python FCM | Local-first, permissive licensing, clear service boundaries, cloud-portable | Requires translation layer for query ergonomics | **Adopt v1** |
+| Apache AGE on Postgres | SQL+graph in one engine, good cloud-side graph semantics | Neon extension support uncertainty, weaker local/cloud parity with SQLite local baseline | Defer |
+| SurrealDB | Strong integrated multi-model experience | BSL posture conflicts with future hosted/open strategy timing | Reject for v1 core |
+| FalkorDB | Graph performance and Redis ecosystem familiarity | SSPL posture conflicts with hosted/open strategy | Reject for v1 core |
+
+## 8) Public APIs / Interfaces
+
+All APIs are proposed MCP tool contracts for Local+ mode.
+
+### Common conventions
+
+1. `project` parameter is optional and follows existing Basic Memory project routing.
+2. Deterministic fields are reproducible with identical inputs and index state.
+3. Probabilistic fields are model-derived scores and include confidence metadata.
+4. Error model uses structured codes and fail-fast behavior.
+
+Shared error codes:
+1. `INVALID_ARGUMENT`
+2. `NOT_FOUND`
+3. `MODEL_INVALID`
+4. `INDEX_NOT_READY`
+5. `RESOURCE_LIMIT_EXCEEDED`
+6. `INTERNAL_ERROR`
+
+---
+
+### 8.1 `graph_lineage(start, goal?)`
+
+**Input schema:**
+```json
+{
+  "start": "string (required, permalink or memory URL)",
+  "goal": "string (optional, concept or decision target)",
+  "max_hops": "integer (optional, default 4, range 1-6)",
+  "relation_filters": ["string"],
+  "project": "string (optional)"
+}
+```
+
+**Output schema:**
+```json
+{
+  "root": {"id": "string", "title": "string", "permalink": "string"},
+  "paths": [
+    {
+      "path_id": "string",
+      "nodes": [{"id": "string", "title": "string"}],
+      "edges": [{"relation": "string", "direction": "outgoing|incoming"}],
+      "deterministic_path_score": 0.0,
+      "confidence": 0.0,
+      "evidence_refs": ["memory://..."]
+    }
+  ],
+  "generated_at": "RFC3339"
+}
+```
+
+**Deterministic fields:** root, nodes, edges, deterministic path score, generated timestamp.  
+**Probabilistic fields:** confidence.
+
+**Latency target:** p95 <= 450ms for `max_hops<=4`, graph envelope up to 50k nodes / 300k edges.
+
+**Scale envelope:**
+1. Tested local baseline: 50k nodes, 300k edges.
+2. Expected degradation: path expansion can exceed latency target when candidate paths > 20k.
+
+---
+
+### 8.2 `graph_impact(target, horizon, relation_filters?)`
+
+**Input schema:**
+```json
+{
+  "target": "string (required)",
+  "horizon": "integer (required, range 1-4)",
+  "relation_filters": ["string"],
+  "include_reasons": "boolean (default true)",
+  "project": "string (optional)"
+}
+```
+
+**Output schema:**
+```json
+{
+  "target": {"id": "string", "title": "string"},
+  "affected": [
+    {
+      "id": "string",
+      "title": "string",
+      "distance": 2,
+      "impact_score": 0.0,
+      "confidence": 0.0,
+      "reasons": ["string"]
+    }
+  ],
+  "summary": {"total_considered": 0, "total_returned": 0}
+}
+```
+
+**Deterministic fields:** membership, distance, summary counts.  
+**Probabilistic fields:** impact score, confidence.
+
+**Latency target:** p95 <= 650ms for `horizon<=3` under baseline envelope.
+
+**Scale envelope:**
+1. `affected` default cap: 200 items.
+2. Hard cap: 1000 items with pagination token.
+
+---
+
+### 8.3 `graph_health(scope?, timeframe?)`
+
+**Input schema:**
+```json
+{
+  "scope": "string (optional, directory prefix or project-wide)",
+  "timeframe": "string (optional, e.g. 30d, 90d)",
+  "project": "string (optional)"
+}
+```
+
+**Output schema:**
+```json
+{
+  "metrics": {
+    "orphan_rate": 0.0,
+    "stale_central_nodes": 0,
+    "overloaded_hubs": 0,
+    "contradiction_candidates": 0
+  },
+  "issues": [
+    {
+      "issue_type": "orphan|stale_central|overloaded_hub|contradiction_candidate",
+      "entity_id": "string",
+      "severity": "low|medium|high",
+      "reason": "string",
+      "suggested_action": "string"
+    }
+  ],
+  "computed_at": "RFC3339"
+}
+```
+
+**Deterministic fields:** metrics and issue list membership for a fixed graph snapshot.  
+**Probabilistic fields:** contradiction candidate confidence when present.
+
+**Latency target:** p95 <= 1500ms project-wide; <= 700ms for scoped directory mode.
+
+**Scale envelope:** project-wide scans tested to 50k nodes.
+
+---
+
+### 8.4 `fcm_simulate(actions, scenario?, clamp_rules?)`
+
+**Input schema:**
+```json
+{
+  "actions": [
+    {"node_id": "string", "delta": 0.2}
+  ],
+  "scenario": {
+    "steps": 12,
+    "activation": "tanh|sigmoid|bounded_linear",
+    "decay": 0.05
+  },
+  "clamp_rules": [
+    {"node_id": "string", "min": -1.0, "max": 1.0}
+  ],
+  "project": "string (optional)"
+}
+```
+
+**Output schema:**
+```json
+{
+  "baseline": [{"node_id": "string", "state": 0.12}],
+  "projected": [{"node_id": "string", "state": 0.43}],
+  "deltas": [{"node_id": "string", "delta": 0.31}],
+  "stability": {
+    "converged": true,
+    "iterations_used": 9,
+    "residual": 0.002
+  },
+  "confidence": 0.0,
+  "explanations": [
+    {"node_id": "string", "top_influencers": [{"source": "string", "weight": 0.7}]}
+  ]
+}
+```
+
+**Deterministic fields:** baseline, projected, deltas, convergence metadata for fixed model and parameters.  
+**Probabilistic fields:** confidence (derived from edge confidence and evidence coverage).
+
+**Latency target:** p95 <= 1000ms for up to 500 nodes / 5000 edges and <=12 steps.
+
+**Scale envelope:**
+1. Soft limit: 2000 nodes / 20000 edges.
+2. Over soft limit: return `RESOURCE_LIMIT_EXCEEDED` with remediation guidance.
+
+---
+
+### 8.5 `fcm_rank_actions(goal, constraints?, top_k?)`
+
+**Input schema:**
+```json
+{
+  "goal": "string (required node_id)",
+  "constraints": {
+    "max_negative_impact": 0.25,
+    "required_tags": ["string"],
+    "disallowed_nodes": ["string"]
+  },
+  "top_k": "integer (default 10, range 1-25)",
+  "project": "string (optional)"
+}
+```
+
+**Output schema:**
+```json
+{
+  "goal": {"node_id": "string", "label": "string"},
+  "recommendations": [
+    {
+      "action_node_id": "string",
+      "expected_goal_delta": 0.0,
+      "risk_penalty": 0.0,
+      "net_score": 0.0,
+      "confidence": 0.0,
+      "rationale": ["string"],
+      "evidence_refs": ["memory://..."]
+    }
+  ]
+}
+```
+
+**Deterministic fields:** candidate action set, constraints compliance.  
+**Probabilistic fields:** expected goal delta, risk penalty, net score, confidence.
+
+**Latency target:** p95 <= 1500ms for top 10 from up to 100 candidate actions.
+
+**Scale envelope:**
+1. Candidate actions hard cap: 1000.
+2. For larger sets, require pre-filtering via tags/scope.
+
+---
+
+### 8.6 `fcm_import_model(source, format)`
+
+**Input schema:**
+```json
+{
+  "source": "string (required path or URI)",
+  "format": "csv_bundle_v1 (required)",
+  "merge_mode": "replace|upsert (default upsert)",
+  "project": "string (optional)"
+}
+```
+
+**Output schema:**
+```json
+{
+  "import_id": "string",
+  "nodes_loaded": 0,
+  "edges_loaded": 0,
+  "warnings": ["string"],
+  "errors": ["string"]
+}
+```
+
+**Deterministic fields:** load counts and validation results.  
+**Probabilistic fields:** none.
+
+**Latency target:** p95 <= 2500ms for 10k edges CSV bundle.
+
+**Scale envelope:**
+1. Maximum CSV rows per import: 250k.
+2. Above limit returns `RESOURCE_LIMIT_EXCEEDED`.
+
+---
+
+### 8.7 `fcm_export_model(format, selection?)`
+
+**Input schema:**
+```json
+{
+  "format": "csv_bundle_v1 (required)",
+  "selection": {
+    "scope": "all|tag|subgraph",
+    "tag": "string (optional)",
+    "seed_nodes": ["string"]
+  },
+  "project": "string (optional)"
+}
+```
+
+**Output schema:**
+```json
+{
+  "export_id": "string",
+  "format": "csv_bundle_v1",
+  "files": [
+    {"name": "nodes.csv", "path": "string"},
+    {"name": "edges.csv", "path": "string"}
+  ],
+  "node_count": 0,
+  "edge_count": 0
+}
+```
+
+**Deterministic fields:** file set and row counts for fixed selection.  
+**Probabilistic fields:** none.
+
+**Latency target:** p95 <= 1800ms for 50k edges export.
+
+**Scale envelope:**
+1. Max export rows: 500k total.
+2. Pagination or scoped export required above cap.
+
+## 9) Data Model and Storage Boundaries
+
+### 9.1 Knowledge graph schema (descriptive)
+
+`KnowledgeNode`:
+1. `id: str`
+2. `kind: note|decision|spec|concept|person|project`
+3. `title: str`
+4. `permalink: str`
+5. `tags: list[str]`
+6. `updated_at: datetime`
+
+`KnowledgeEdge`:
+1. `id: str`
+2. `src_id: str`
+3. `dst_id: str`
+4. `relation: str`
+5. `directionality: directed|bidirectional`
+6. `evidence_refs: list[str]`
+7. `confidence: float [0,1]`
+8. `updated_at: datetime`
+
+### 9.2 FCM schema (causal signed weighted)
+
+`FCMNode`:
+1. `id: str`
+2. `label: str`
+3. `node_type: goal|driver|risk|intervention|context`
+4. `state: float [-1,1]`
+5. `clamp_min: float`
+6. `clamp_max: float`
+7. `metadata: map`
+
+`FCMEdge`:
+1. `id: str`
+2. `source_id: str`
+3. `target_id: str`
+4. `weight: float [-1,1]`
+5. `confidence: float [0,1]`
+6. `time_decay: float [0,1]`
+7. `evidence_refs: list[str]`
+8. `updated_at: datetime`
+
+### 9.3 Provenance model
+
+`ProvenanceRecord`:
+1. `entity_id: str`
+2. `evidence_refs: list[str]`
+3. `confidence: float [0,1]`
+4. `updated_at: datetime`
+5. `source_type: extracted|user_authored|imported`
+
+### 9.4 Scenario model
+
+`Scenario`:
+1. `id: str`
+2. `name: str`
+3. `interventions: list[{node_id, delta}]`
+4. `constraints: list[{node_id, min, max}]`
+5. `steps: int`
+6. `activation: tanh|sigmoid|bounded_linear`
+7. `created_at: datetime`
+8. `created_by: str`
+
+`ScenarioResult`:
+1. `scenario_id: str`
+2. `converged: bool`
+3. `iterations_used: int`
+4. `residual: float`
+5. `goal_deltas: list[{node_id, delta}]`
+6. `confidence: float [0,1]`
+
+### 9.5 Storage boundaries
+
+| Layer | System of Record | Purpose | Rebuildable |
+|---|---|---|---|
+| Markdown files | File system | Canonical knowledge content | No |
+| SQLite entities/relations/embeddings | SQLite | Operational queries and project state | Yes (from markdown + embedding pipeline) |
+| Knowledge graph triples | Oxigraph | Fast graph traversal and pattern queries | Yes |
+| FCM model and snapshots | SQLite + optional artifacts | Causal model state and scenario history | Yes (from imports and authored model definitions) |
+
+## 10) Mental Modeler Interoperability
+
+### v1 interoperability contract
+
+Format: `csv_bundle_v1`
+1. `nodes.csv`
+2. `edges.csv`
+3. Optional `scenarios.csv`
+
+`nodes.csv` required columns:
+1. `node_id`
+2. `label`
+3. `node_type`
+4. `state`
+5. `clamp_min`
+6. `clamp_max`
+
+`edges.csv` required columns:
+1. `edge_id`
+2. `source_id`
+3. `target_id`
+4. `weight`
+5. `confidence`
+6. `evidence_refs` (semicolon-delimited)
+
+### Import rules
+
+1. Missing required columns fail with `MODEL_INVALID`.
+2. Unknown node types fail fast.
+3. Weight and confidence ranges are strictly validated.
+4. Import returns warnings for dangling evidence references.
+
+### Export rules
+
+1. Preserve stable IDs for round-trip compatibility.
+2. Preserve signed weights exactly.
+3. Preserve confidence values exactly.
+4. Non-portable metadata is emitted to `metadata.json` sidecar when present.
+
+### Native file translators
+
+1. Native project-format translation is deferred to v2.
+2. CSV remains the guaranteed compatibility baseline in v1 and v1.5.
+
+## 11) Pricing and Packaging
+
+### Tier structure
+
+| Tier | Price Monthly | Price Annual | Beta Price (25% off) | Target Persona | Core Value |
+|---|---:|---:|---:|---|---|
+| OSS Local | $0 | $0 | $0 | Casual local users | Retrieval and memory basics |
+| Local+ Graph Intelligence | $9 | $90 | $6.75 monthly / $67.50 annual | Founders, consultants, researchers | Safer changes + explainable graph + FCM simulation |
+| Cloud Pro (current anchor) | $19 | $190 | $14.25 monthly / $142.50 annual | Users who need hosted sync and cloud workflows | Managed cloud + sync + collaboration path |
+
+Pricing principles:
+1. Local+ is intentionally priced between free OSS and cloud to capture users who need deeper intelligence but not hosted sync.
+2. Cloud Pro remains the hosted convenience anchor and future collaboration path.
+3. Local+ must stand on standalone local value and cannot depend on cloud features.
+
+### Feature gate mapping
+
+| Capability | OSS Local | Local+ | Cloud Pro |
+|---|---|---|---|
+| Search and basic context tools | Yes | Yes | Yes |
+| Decision Lineage | No | Yes | Yes |
+| Impact Radius | No | Yes | Yes |
+| Graph Health | No | Yes | Yes |
+| FCM simulate + rank | No | Yes | Yes |
+| CSV model import/export | No | Yes | Yes |
+| Hosted collaboration controls | No | No | Future add-on |
+
+### Packaging decisions
+
+1. Local+ remains fully local-capable and does not require cloud auth to run.
+2. Cloud Pro remains the hosted convenience and collaboration anchor.
+3. Future hosted research add-on will layer on Cloud Pro after v2 readiness.
+
+## 12) Rollout Strategy
+
+### 12.1 Document production iterations (locked)
+
+Iteration 1 (draft complete):
+1. Complete all 15 sections in one pass.
+2. Include v1/v1.5/v2 cut lines.
+3. Include pricing and scenario definitions.
+4. Ensure no placeholders.
+
+Iteration 2 (hardening and decision lock):
+1. Resolve cross-section contradictions.
+2. Convert uncertain language to locked decisions.
+3. Add measurable acceptance criteria and risk owners.
+4. Finalize execution-ready API contracts.
+
+### 12.2 Product rollout phases
+
+Phase A: Foundation release (v1)
+1. Graph lineage, impact, health.
+2. CSV model import/export.
+3. FCM simulation and ranking.
+4. Advanced mode UX gating for research-grade controls.
+
+Phase B: Quality and confidence (v1.5)
+1. Contradiction Watch.
+2. Priority Briefs.
+3. Improved uncertainty propagation.
+4. Confidence calibration pass using real-world model feedback.
+
+Phase C: Team expansion (v2)
+1. Hosted team governance.
+2. Shared model controls.
+3. Extended translator support.
+
+### 12.3 Go/No-Go release gates
+
+Gate to ship v1 default workflows:
+1. p95 latency targets are met within the declared scale envelopes.
+2. Scenario round-trip fidelity tests pass for CSV import/export.
+3. Every recommendation and simulation path exposes evidence references and confidence.
+
+Gate to ship v1.5:
+1. Contradiction Watch precision is acceptable for default-on use.
+2. Confidence calibration reduces false-confidence reports in user testing.
+
+Gate to ship v2 team features:
+1. Clear willingness-to-pay signal from team and research buyers.
+2. Cloud execution path preserves local-cloud semantic parity for core contracts.
+
+## 13) Risks, Counterarguments, and Mitigations
+
+| Risk | Counterargument | Severity | Likelihood | Mitigation | Owner |
+|---|---|---|---|---|---|
+| "This is just better search" | Positioning can collapse into technical jargon | High | Medium | Lead with decision safety and explainability outcomes in product copy and onboarding | Product Lead |
+| FCM feels opaque or invented | Users distrust black-box scoring | High | Medium | Require evidence refs and confidence disclosure on every recommendation | Applied AI Lead |
+| Local performance regressions | Multi-hop and simulation can feel slow on laptops | Medium | Medium | Enforce envelopes, caps, and fail-fast limit errors with guidance | Engineering Lead |
+| Research features overwhelm casual users | UX complexity can reduce adoption | Medium | High | Default to guided flows and hide advanced controls behind explicit advanced mode | Design Lead |
+| License/roadmap conflict if backend changes | Later swap to restrictive engines creates GTM risk | High | Low | Lock permissive v1 stack and require leadership sign-off for any license-restricted dependency | Product + Legal |
+| Interop mismatch with external tools | Round-trip drift harms trust with researchers | Medium | Medium | Validate node and edge parity in import/export tests and version interop schema | Integrations Lead |
+| Pricing confusion between Local+ and Cloud Pro | Buyers may not understand which tier fits | Medium | Medium | Publish explicit tier comparison focused on local intelligence vs hosted collaboration | GTM Lead |
+
+## 14) Acceptance Criteria
+
+### 14.1 Document acceptance criteria
+
+1. Product, technical, and pricing decisions are explicit and unambiguous.
+2. API contracts include input/output schemas, error models, deterministic versus probabilistic fields, and performance envelopes.
+3. v1/v1.5/v2 cut lines are explicit and consistent.
+4. Risk register includes severity, likelihood, owner, and mitigation.
+5. Document can be handed to implementation without additional architecture decisions.
+6. Leadership can use this document directly for pricing and positioning decisions.
+
+### 14.2 Product acceptance criteria for v1 delivery
+
+1. `graph_lineage`, `graph_impact`, `graph_health`, `fcm_simulate`, `fcm_rank_actions`, `fcm_import_model`, and `fcm_export_model` are available as Local+ contracts.
+2. Local mode executes all v1 contracts without cloud dependency.
+3. API p95 latency targets are met within defined scale envelopes.
+4. Every ranked or simulated output includes evidence-linked rationale and confidence.
+5. CSV round-trip preserves node count, edge count, and signed weights exactly.
+
+### 14.3 Scenario test matrix (required)
+
+1. **Casual local user impact check**
+Expected pass:
+`graph_impact` returns ranked affected notes with reasons before a note edit.
+
+2. **Research workflow simulation**
+Expected pass:
+User imports a model bundle, runs `fcm_simulate`, and receives converged deltas and rationale.
+
+3. **Decision audit traceability**
+Expected pass:
+`graph_lineage` returns path and evidence references that explain recommendation origin.
+
+4. **Cloud and local parity**
+Expected pass:
+Identical query inputs return semantically equivalent outputs in local and cloud modes with local fallback behavior when cloud is unavailable.
+
+5. **Sparse or contradictory graph behavior**
+Expected pass:
+System degrades gracefully with explicit uncertainty and does not fabricate high-confidence recommendations.
+
+6. **Interop round-trip fidelity**
+Expected pass:
+`fcm_export_model` then `fcm_import_model` preserves node and edge counts and signed weights without mutation.
+
+## 15) Appendix (license notes, terminology, examples)
+
+### 15.1 License notes (verified 2026-03-05)
+
+1. SurrealDB core licensing is published under BSL 1.1 with DBaaS-related restrictions in its conversion window.
+2. FalkorDB is published under SSPLv1.
+3. pyoxigraph is dual-licensed Apache-2.0 or MIT.
+4. Neon extension catalog currently does not list Apache AGE as a supported extension.
+
+These notes support the v1 dependency decisions in this document.
+
+### 15.2 Terminology
+
+1. **Knowledge graph:** descriptive relation graph derived from markdown knowledge.
+2. **FCM:** fuzzy cognitive model with signed weighted causal edges.
+3. **Deterministic field:** reproducible output field from fixed input and fixed model/index snapshot.
+4. **Probabilistic field:** score influenced by confidence weights and model uncertainty.
+
+### 15.3 Assumptions and defaults
+
+1. Markdown remains source of truth.
+2. SQLite remains mandatory baseline.
+3. Graph and FCM capabilities are premium Local+ features, not OSS defaults.
+4. Research-heavy features are advanced mode, while mainstream UX stays guided.
+5. Mental Modeler interoperability starts with CSV contract first; native translator support is deferred.
+
+### 15.4 Out of scope for this document
+
+1. Implementation code changes.
+2. Database migrations.
+3. Cloud infrastructure edits.
+4. Full instrumentation pilot plan as the primary artifact.
+
+### 15.5 External references
+
+1. [SurrealDB licensing](https://surrealdb.com/license)
+2. [FalkorDB licensing](https://docs.falkordb.com/References/license.html)
+3. [pyoxigraph package and license](https://pypi.org/project/pyoxigraph/)
+4. [Neon Postgres extension catalog](https://neon.com/docs/extensions/pg-extensions)
@@ -0,0 +1,299 @@
+# SPEC-LOCAL-GRAPH-INTELLIGENCE: Technical Addendum (Graph + FCM)
+
+**Status:** Draft  
+**Date:** 2026-03-05  
+**Owner:** Basic Memory
+**Current Phase (2026-03-05):** Contract skeleton implementation is complete; next active phase is SQL-backed graph capabilities.
+
+Related product spec:
+`/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE.md`
+
+Related execution spec:
+`/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-IMPLEMENTATION-PLAN.md`
+
+## Why This Addendum Exists
+
+The product spec defines user value. This addendum defines the technical shape that can deliver that value without
+breaking local-first principles.
+
+This addendum also introduces a second graph layer:
+
+1. Knowledge graph for relationships between notes, entities, and decisions.
+2. Fuzzy Cognitive Model (FCM) graph for weighted causal reasoning over actions and outcomes.
+
+Both are derived from markdown and optional user-provided models.
+
+## Strategic Reality Check
+
+This is a strong idea if we stage it correctly.
+
+It is not a pipe dream if we avoid one trap: building a big "graph platform" before proving users repeatedly use
+decision simulation workflows.
+
+The correct strategy is:
+
+1. Launch high-precision graph insights first.
+2. Add FCM scoring where it changes user behavior (not as a novelty dashboard).
+3. Expand to hosted/team workflows only after local usage proves repeat value.
+
+## Constraints and Design Principles
+
+1. SQLite remains the operational source for entities, observations, relations, and embeddings.
+2. Markdown remains source of truth.
+3. Graph indexes are derived, rebuildable, and disposable.
+4. Premium local mode must run fully offline.
+5. Cloud deployment should support both single-tenant and SaaS later.
+6. Avoid licenses that constrain hosted/open-source strategy.
+
+## Backend Recommendation
+
+### Primary Recommendation
+
+Use a dual-store architecture:
+
+1. SQLite (existing): operational data, metadata filters, embeddings, and most retrieval.
+2. Oxigraph/pyoxigraph (new): derived graph index for graph traversal and graph-pattern queries.
+3. Python simulation layer (new): FCM state propagation, scenario runs, and decision scoring.
+
+Why this is the best fit:
+
+1. Permissive licensing profile.
+2. Works locally with low footprint.
+3. Cloud-compatible as sidecar service while keeping Neon Postgres as core cloud store.
+4. Clear boundary between graph query and numeric simulation concerns.
+
+### Candidate Trade-Offs
+
+#### Oxigraph/pyoxigraph
+
+Pros:
+
+1. Lightweight local embedding.
+2. Good fit for derived-index strategy.
+3. Strong path for standards-based graph representation.
+
+Cons:
+
+1. SPARQL fluency is less common than SQL/Cypher.
+2. Requires a translation layer so product features are not query-language-coupled.
+
+#### Apache AGE (Postgres extension)
+
+Pros:
+
+1. SQL + graph in one engine.
+2. Attractive for cloud-side graph operations.
+
+Cons:
+
+1. Neon support is uncertain for this extension.
+2. Local/cloud parity is harder if local uses SQLite.
+
+#### SurrealDB / FalkorDB
+
+Pros:
+
+1. Strong graph-oriented developer experience.
+
+Cons:
+
+1. License posture is misaligned with a future hosted/open-source roadmap unless commercial terms are accepted.
+
+Decision:
+Do not make these core dependencies for v1 of Local+ Graph Intelligence.
+
+## Two-Graph Model
+
+### A) Knowledge Graph (Descriptive)
+
+Node examples:
+
+1. Note
+2. Decision
+3. Spec
+4. Person
+5. Project
+6. Concept
+
+Edge examples:
+
+1. `depends_on`
+2. `informed_by`
+3. `contradicts`
+4. `supports`
+5. `implements`
+6. `derived_from`
+
+Purpose:
+Power navigation, lineage, path explanation, impact radius, and health checks.
+
+### B) FCM Graph (Causal, Signed, Weighted)
+
+Node examples:
+
+1. Goal: "Reduce regressions"
+2. Driver: "Test coverage"
+3. Risk: "Scope creep"
+4. Intervention: "Add review gate"
+5. Context variable: "Team bandwidth"
+
+Edge attributes:
+
+1. `weight` in [-1.0, 1.0]
+2. `confidence` in [0.0, 1.0]
+3. `evidence_refs` (links to notes/specs)
+4. `time_decay` (optional)
+
+Purpose:
+Power scenario simulation and action ranking, not generic retrieval.
+
+## Premium Feature Mapping to Architecture
+
+### Decision Lineage
+
+Backed by:
+
+1. Knowledge graph path queries.
+2. Evidence references stored on edges.
+
+### Impact Radius
+
+Backed by:
+
+1. Multi-hop neighborhood expansion with relation-type weights.
+2. Risk ranking using centrality + recency + confidence.
+
+### Contradiction Watch
+
+Backed by:
+
+1. Candidate contradiction edges.
+2. Confidence-scored reconciliation queue.
+
+### Priority Briefs
+
+Backed by:
+
+1. Health metrics (orphan rate, stale-central nodes, unresolved contradictions).
+2. Optional FCM "top leverage actions" summary.
+
+### New Premium Feature: Action Simulator
+
+Backed by:
+
+1. FCM scenario runs over selected action nodes.
+2. Ranked interventions with expected positive/negative downstream effects.
+3. Explicit rationale graph for every recommendation.
+
+## Mental Modeler Interop Plan
+
+Goal:
+Make Basic Memory the AI-enabled operating layer around existing researcher workflows, not a replacement for their tools.
+
+Interoperability phases:
+
+1. Import/export edge lists and node tables via CSV as the baseline interchange.
+2. Preserve concept IDs and metadata so round-trips remain stable.
+3. Add translator support for native model files if/when schema contracts are validated with partner data.
+
+Validation requirement:
+
+1. Round-trip tests must preserve node count, edge count, and signed weights.
+2. Confidence/evidence metadata may be Basic Memory extensions and should degrade gracefully when exported.
+
+## Suggested Tool/API Surface (Product-Facing)
+
+1. `graph_lineage(start, goal?)`  
+   Returns explainable evidence paths.
+2. `graph_impact(target, horizon=2..4)`  
+   Returns ranked affected nodes with reasons.
+3. `graph_health()`  
+   Returns actionable graph quality issues.
+4. `fcm_simulate(actions, scenario?)`  
+   Returns projected effects and uncertainty.
+5. `fcm_rank_actions(goal, constraints?)`  
+   Returns top candidate actions with trade-offs.
+6. `fcm_import_model(source)` / `fcm_export_model(format)`  
+   Handles interop with external cognitive mapping workflows.
+
+## Local and Cloud Deployment Shape
+
+### Local (Primary)
+
+1. SQLite + local embeddings.
+2. Oxigraph as local sidecar/index library.
+3. FCM simulation in process.
+
+### Cloud (Future-Compatible)
+
+1. Neon Postgres remains system of record in hosted mode.
+2. Graph index service runs per tenant or shared multi-tenant with strict tenancy boundaries.
+3. FCM simulation service can run stateless workers reading graph snapshots.
+
+Principle:
+Do not require cloud to run premium local features.
+
+## Rollout Plan With Go/No-Go Gates
+
+### Phase 0: Proof of Utility (4-6 weeks)
+
+Deliver:
+
+1. Decision Lineage
+2. Impact Radius
+3. CSV FCM import + `fcm_simulate` prototype
+
+Gate to continue:
+
+1. Repeated weekly usage by pilot users.
+2. Users report changed decisions, not just curiosity clicks.
+
+### Phase 1: Productized Local+ Beta
+
+Deliver:
+
+1. Graph health workflow
+2. Contradiction Watch
+3. Action ranking with explicit rationale
+
+Gate to continue:
+
+1. Retention of graph features after first month.
+2. Measured reduction in "surprise side effects" after edits.
+
+### Phase 2: Hosted Expansion
+
+Deliver:
+
+1. Optional cloud execution for heavy simulations.
+2. Team-shared model governance.
+
+Gate to continue:
+
+1. Clear willingness to pay for hosted collaboration.
+
+## Risks and Mitigations
+
+Risk: FCM outputs feel "made up."  
+Mitigation: Require evidence links and confidence scoring in every recommendation.
+
+Risk: Research-heavy feature alienates casual users.  
+Mitigation: Keep FCM features in an advanced mode; default to concise guidance workflows.
+
+Risk: Overengineering early graph stack.  
+Mitigation: Keep derived-index architecture and strict phase gates tied to behavior change.
+
+Risk: Interop friction with external tooling.  
+Mitigation: Start with transparent CSV contract and strict round-trip validation.
+
+## Candid Recommendation
+
+Pursue this. It is a high-upside differentiation path for Local+ if executed with staged validation.
+
+The key is to sell outcomes:
+
+1. "Safer decisions"
+2. "Explainable recommendations"
+3. "Faster synthesis for complex research"
+
+Avoid selling "graph DB" as the product. That is implementation detail.
@@ -0,0 +1,262 @@
+# SPEC-LOCAL-GRAPH-INTELLIGENCE: Premium Local Graph Intelligence
+
+**Status:** Draft  
+**Date:** 2026-03-05  
+**Owner:** Basic Memory
+**Current Phase (2026-03-05):** Phase 1 contract foundation shipped; engineering is now executing SQL-backed Phase 2 graph logic.
+
+Companion technical addendum:
+`/docs/specs/SPEC-LOCAL-GRAPH-INTELLIGENCE-TECHNICAL-ADDENDUM.md`
+
+## Summary
+
+Add a premium local feature that turns Basic Memory from "search and recall" into "explain and guide."
+
+The value is not a new database. The value is better decisions for local users:
+
+1. Understand why something matters.
+2. See what will be affected before making a change.
+3. Detect weak spots in the knowledge base early.
+4. Navigate complex knowledge intentionally instead of loading everything.
+
+This feature is additive. Existing local workflows remain intact.
+
+## Positioning
+
+Core message:
+"Your notes do more than store knowledge. They reveal consequences, lineage, and blind spots."
+
+Local user promise:
+
+1. Keep files local.
+2. Keep markdown as source of truth.
+3. Get advanced graph intelligence as an opt-in premium capability.
+
+## Problem
+
+Today, deep graph navigation is possible but often expensive in context size and hard to steer for complex questions.
+Users can find information, but they still do manual synthesis to answer:
+
+1. What changed because of this note?
+2. Why did we decide this?
+3. What might break if I update this?
+4. Which parts of the graph are stale, isolated, or contradictory?
+
+The cost is time, cognitive load, and missed risk.
+
+## Goals
+
+1. Provide clear, explainable graph insights that users can act on.
+2. Make deep navigation feel guided, not overwhelming.
+3. Help users prevent mistakes before they happen.
+4. Create premium local value that is easy to understand and justify.
+5. Keep feature behavior transparent and trustworthy.
+
+## Non-Goals
+
+1. Replacing SQLite as the primary operational store.
+2. Changing markdown as source of truth.
+3. Forcing users to learn graph query languages.
+4. Building a cloud-only feature set.
+5. Turning Basic Memory into an enterprise BI product.
+
+## Product Frame: From Retrieval to Reasoning
+
+The feature should be framed as a shift in user outcome:
+
+1. Retrieval: "Find me the note."
+2. Reasoning: "Show me the path, impact, and confidence around this note."
+
+This is the main narrative upgrade for premium local users.
+
+## Premium Value Pillars
+
+### 1) Decision Confidence
+
+Users can see decision lineage:
+
+1. What evidence supported a decision.
+2. Which notes/specs informed it.
+3. How that decision evolved over time.
+
+### 2) Change Safety
+
+Users can run impact-aware workflows:
+
+1. Estimate blast radius before editing.
+2. Surface downstream dependencies.
+3. Prioritize what to review first.
+
+### 3) Knowledge Quality
+
+Users can maintain graph health:
+
+1. Detect orphaned notes.
+2. Detect overloaded hub notes.
+3. Detect stale but high-centrality notes.
+4. Detect likely contradictions.
+
+### 4) Guided Navigation
+
+Users can explore deeper relationships without context explosion:
+
+1. Follow promising branches.
+2. Stop when confidence is sufficient.
+3. Avoid "load everything and hope."
+
+## Feature Catalog (Value-First)
+
+### A. Decision Lineage
+
+What users get:
+
+1. A clear "why chain" for important conclusions.
+2. Traceable connections to supporting notes.
+3. Better handoffs and historical understanding.
+
+### B. Impact Radius
+
+What users get:
+
+1. A ranked list of likely affected notes before edits.
+2. Safer refactors for docs, plans, and architecture.
+3. Reduced accidental drift and inconsistency.
+
+### C. Knowledge Health Dashboard
+
+What users get:
+
+1. Weekly health signals for the graph.
+2. Actionable cleanup targets.
+3. Better long-term memory quality with less manual auditing.
+
+### D. Path Explorer
+
+What users get:
+
+1. "Show me how A connects to B" style explanations.
+2. Multiple candidate paths with confidence cues.
+3. Better discovery across large note collections.
+
+### E. Contradiction Watch
+
+What users get:
+
+1. Early warnings for conflicting statements.
+2. Suggested reconciliation workflow.
+3. Higher trust in the knowledge base.
+
+### F. Priority Briefs
+
+What users get:
+
+1. Periodic "what matters now" graph summaries.
+2. Focused recommendations, not noisy activity dumps.
+3. Better focus for solo builders and small teams.
+
+## User Personas and Why They Pay
+
+### Solo Technical Founder
+
+Pain:
+Cannot hold full architecture and decision history in working memory.
+
+Premium value:
+Impact Radius + Decision Lineage prevent rework and regressions.
+
+### Product/Research Lead
+
+Pain:
+Knowledge is fragmented across specs, notes, and decisions.
+
+Premium value:
+Path Explorer + Priority Briefs compress synthesis time.
+
+### Consultant/Fractional Operator
+
+Pain:
+Frequent context switching across domains and clients.
+
+Premium value:
+Knowledge Health + Decision Lineage speed onboarding and reporting.
+
+## Packaging Direction
+
+Suggested packaging:
+
+1. OSS Local: existing search + context tools.
+2. Local+ Graph Intelligence: advanced graph insight features listed above.
+3. Future Team Add-On: shared policies, shared graph health views, shared lineage views.
+
+Core upsell line:
+"Keep your local workflow. Add graph intelligence when complexity grows."
+
+## Experience Principles
+
+1. Explainability first.
+Every advanced result should show "why this was suggested."
+
+2. Actionability over novelty.
+Insights should lead to concrete next steps, not abstract charts.
+
+3. Progressive disclosure.
+Start with concise summaries, expand on demand.
+
+4. Deterministic where possible.
+Users should trust repeated runs of the same workflow.
+
+5. Respect local-first expectations.
+No surprise cloud dependency in premium local mode.
+
+## Success Criteria (Product)
+
+1. Users can describe the benefit in one sentence:
+"It shows me what matters and what breaks before I change things."
+2. Premium users report lower time-to-understanding for complex topics.
+3. Premium users report fewer "surprise side effects" after edits.
+4. Premium users keep larger knowledge graphs healthy with less manual effort.
+5. Feature adoption is driven by outcomes, not by curiosity-only usage.
+
+## Risks and Mitigations
+
+Risk: Feature sounds like "just better search."  
+Mitigation: Lead messaging with decision confidence and change safety, not traversal depth.
+
+Risk: Feature feels too advanced for normal users.  
+Mitigation: Package as guided insights and reports, not as a query language.
+
+Risk: Insight quality feels noisy.  
+Mitigation: Focus launch scope on high-precision insight types and transparent rationale.
+
+Risk: Value is hard to prove.  
+Mitigation: Track user-facing outcomes (time saved, risk avoided, cleanup completed).
+
+## Rollout Narrative
+
+Phase 1: "Safer Changes"
+
+1. Impact Radius
+2. Decision Lineage
+
+Phase 2: "Health and Clarity"
+
+1. Knowledge Health Dashboard
+2. Contradiction Watch
+
+Phase 3: "Strategic Navigation"
+
+1. Path Explorer
+2. Priority Briefs
+
+## One-Line Positioning Options
+
+1. "Local notes, strategic intelligence."
+2. "Know what changed, why it matters, and what it affects."
+3. "From note-taking to decision support."
+
+## Open Questions
+
+1. Which two features best define the paid tier at launch?
+2. Which insight types should be guaranteed deterministic in v1?
+3. Should Priority Briefs be bundled or separate as an add-on?
+4. What is the simplest in-product education flow for first-time premium users?