@awareness-sdk/local 0.1.0

package/src/spec/awareness-spec.json

@@ -0,0 +1,393 @@
+{
+  "version": 2,
+  "markers": {
+    "start": "<!-- AWARENESS_RULES_START -->",
+    "end": "<!-- AWARENESS_RULES_END -->"
+  },
+
+  "core_lines": [
+    "## Awareness Memory Integration (MANDATORY)",
+    "",
+    "awareness_* = cross-session persistent memory (past decisions, knowledge, tasks).",
+    "Other tools = current codebase navigation (file search, code index).",
+    "Use BOTH - they serve different purposes.",
+    "",
+    "STEP 1 - SESSION START:",
+    "  Call awareness_init(source=\"{source}\") -> get session_id, review context.",
+    "  If active_skills[] is returned: skill = reusable procedure done 2+ times;",
+    "  summary = injectable instruction, methods = steps. Apply matching skills to tasks.",
+    "",
+    "STEP 2 - RECALL BEFORE WORK (progressive disclosure):",
+    "  1. awareness_recall(semantic_query=..., keyword_query=..., detail='summary') → lightweight index.",
+    "  2. Review summaries/scores, pick relevant IDs.",
+    "  3. awareness_recall(detail='full', ids=[...]) → expand only what you need.",
+    "",
+    "STEP 3 - RECORD EVERY CHANGE:",
+    "  After EVERY code edit, decision, or bug fix:",
+    "  awareness_record(content=<detailed natural language description>,",
+    "    insights={knowledge_cards:[...], action_items:[...], risks:[...]})",
+    "  Content should be RICH and DETAILED — include reasoning, key code snippets,",
+    "  user quotes, alternatives considered, and files changed. Do NOT compress into",
+    "  a single-line summary. The content IS the memory — more detail = better recall.",
+    "  Include insights to create searchable knowledge in ONE step (recommended).",
+    "  Skipping = permanent data loss.",
+    "",
+    "STEP 4 - CATEGORY GUIDE (for insights.knowledge_cards):",
+    "  - decision = choice made between alternatives.",
+    "  - problem_solution = bug/problem plus the fix that resolved it.",
+    "  - workflow = process, setup, or configuration steps only.",
+    "  - pitfall = blocker, warning, or limitation without a fix yet.",
+    "  - insight = reusable pattern or general learning.",
+    "  - skill = reusable procedure done 2+ times; summary = injectable instruction, methods = steps.",
+    "  - key_point = important technical fact when nothing else fits.",
+    "  Never default everything to workflow.",
+    "",
+    "STEP 5 - SESSION END:",
+    "  awareness_record(content=[step1, step2, ...], insights={...}) with final summary.",
+    "",
+    "BACKFILL (if applicable):",
+    "  If MCP connected late: awareness_record(content=<transcript>)",
+    "",
+    "RULES VERSION: Pass rules_version=\"2\" to awareness_init so the server knows you have these rules.",
+    "If the server returns _setup_action, the rules have been updated — follow the instruction to re-sync.",
+    "",
+    "NOTE: memory_id from X-Awareness-Memory-Id header. source/actor/event_type auto-inferred."
+  ],
+
+  "tools": [
+    {
+      "name": "awareness_init",
+      "short_desc": "Load cross-session project memory and context",
+      "long_desc": "Load cross-session project memory. Returns session_id, context (narratives, tasks, knowledge, active_skills), and usage rules. Call ONCE at session start."
+    },
+    {
+      "name": "awareness_get_agent_prompt",
+      "short_desc": "Fetch full activation prompt for a specific agent role (sub-agent spawning)",
+      "long_desc": "Fetch the full activation prompt for a specific agent role. Call before spawning a sub-agent to get its dedicated system prompt."
+    },
+    {
+      "name": "awareness_recall",
+      "short_desc": "Semantic + keyword hybrid recall with progressive disclosure (detail=summary→full)",
+      "long_desc": "Recall from persistent memory — semantic + keyword hybrid search with progressive disclosure. Use detail='summary' (default) for a lightweight index of matching items, then detail='full' with ids=[...] to expand only the relevant ones. This two-phase pattern saves tokens and improves accuracy. token_budget is deprecated — use detail+ids instead. Set include_installed=true (default) to also search installed market memories; results are merged by score and tagged with source_type."
+    },
+    {
+      "name": "awareness_lookup",
+      "short_desc": "Structured data: tasks, knowledge, risks, timeline",
+      "long_desc": "Fast structured data lookup (<50ms). Types: context, tasks, knowledge, risks, session_history, timeline, handoff."
+    },
+    {
+      "name": "awareness_record",
+      "short_desc": "Record what you did/decided/learned to persistent memory",
+      "long_desc": "Unified write to memory. Pass content (str, list, or dict) + insights={...} to record events and create knowledge cards in ONE call. Content auto-detected: str=single event, list=batch, str+scope=knowledge for docs. Actions: write (default), update_task."
+    }
+  ],
+
+  "mcp_instructions": [
+    "You have a cognitive memory cloud with Auto-Cognition. Use it automatically — never wait for the user to say \"remember\".",
+    "",
+    "Do these 3 things every session:",
+    "",
+    "1. FIRST THING: awareness_init → get session_id + past context. Always do this before any work.",
+    "2. BEFORE WORK: awareness_recall → check what you already know. Don't re-solve solved problems.",
+    "3. AFTER CHANGES: awareness_record(content=<detailed description>, insights={...}) → save what you did/decided/learned. Be detailed — include reasoning, code snippets, user quotes.",
+    "",
+    "RECOMMENDED: Pass insights={knowledge_cards:[...], action_items:[...], risks:[...]} with awareness_record to create searchable knowledge in ONE step — no round-trip needed.",
+    "Knowledge cards MUST be created. Skipping = the memory is stored but never structured into reusable knowledge.",
+    "",
+    "SETUP — when awareness_init returns \"_setup_action\" in the response:",
+    "You MUST follow the instruction to write rules to the specified file. This enables your persistent memory workflow for all future sessions."
+  ],
+
+  "workflow_reference": {
+    "steps": [
+      {
+        "step": 1,
+        "action": "awareness_init",
+        "when": "FIRST thing every session",
+        "what": "Get session_id + past context (recent summaries, open tasks, knowledge cards, active_skills)",
+        "done_check": "You have a session_id. If active_skills[] returned, note them for task matching."
+      },
+      {
+        "step": 2,
+        "action": "awareness_recall (two-phase progressive disclosure)",
+        "when": "BEFORE starting work on any task",
+        "what": "Phase 1: awareness_recall(semantic_query=..., keyword_query=..., detail='summary') → lightweight index. Phase 2: awareness_recall(detail='full', ids=[...relevant IDs...]) → expand only what you need.",
+        "example": "awareness_recall(semantic_query=\"How was auth implemented?\", keyword_query=\"auth JWT\", detail=\"summary\") → review → awareness_recall(detail=\"full\", ids=[\"id1\",\"id2\"])",
+        "done_check": "You've retrieved summaries, selected relevant items, and expanded the ones you need"
+      },
+      {
+        "step": 3,
+        "action": "awareness_record with inline insights",
+        "when": "AFTER every code edit, decision, or bug fix",
+        "what": "awareness_record(content=<detailed description with reasoning, code snippets, user quotes, files changed>, insights={knowledge_cards:[...], action_items:[...], risks:[...]})",
+        "done_check": "Every meaningful change has been recorded WITH rich detail AND structured insights"
+      },
+      {
+        "step": 4,
+        "action": "handle _extraction_instruction (legacy fallback)",
+        "when": "awareness_record response contains _extraction_instruction (only when insights was omitted)",
+        "what": "Follow the instruction to extract insights, then call awareness_record(content=<json>)",
+        "warning": "Skipping this = memories stored but NO searchable knowledge cards created"
+      }
+    ],
+    "tips": {
+      "recall_vs_lookup": "awareness_recall = search by meaning (semantic), use detail='summary' then detail='full'+ids for progressive disclosure. awareness_lookup = get by type (exact DB, <50ms).",
+      "session_end": "Call awareness_record(content=[step1, step2, ...], insights={...}) with a final summary.",
+      "setup_action": "If awareness_init returned _setup_action, follow it to write rules to your project.",
+      "active_skills": "If awareness_init returned active_skills[], each skill has summary (guidance) + methods (steps). Apply matching skills to tasks — do not re-derive their patterns."
+    }
+  },
+
+  "init_guides": {
+    "write_guide": "Write DETAILED content in awareness_record — include reasoning, alternatives considered, key code snippets, user quotes, and files changed. Do NOT compress into a single-line summary; the content IS the memory. RECOMMENDED: pass insights={knowledge_cards:[{category,title,summary,status,tags,confidence}], action_items:[{title,priority,status}], risks:[{title,level,detail}]} to create searchable knowledge in ONE step. Categories: decision|problem_solution|workflow|key_point|pitfall|insight|skill|personal_preference|important_detail|plan_intention.",
+    "search_guide": "Use progressive disclosure for best recall results: 1) Call awareness_recall(semantic_query=<full question>, keyword_query=<2-5 precise terms>, detail='summary') to get a lightweight index with scores. 2) Review summaries and relevance scores to decide which items matter. 3) Call awareness_recall(detail='full', ids=[<relevant IDs>]) to fetch complete content for only what you need. This saves tokens and improves accuracy. token_budget is deprecated — use the detail+ids two-phase pattern instead.",
+    "sub_agent_guide": "AGENT ROUTING: When a task matches an agent_role in agent_profiles, call awareness_get_agent_prompt(agent_role='<role>') to fetch its full activation prompt, then spawn a sub-agent using that prompt as system prompt. Pass agent_role='<role>' to ALL awareness_* calls within the sub-agent. Do NOT pre-fetch all agent prompts — only fetch when actually spawning.",
+    "skill_guide": "SKILLS ACTIVE: active_skills[] contains reusable skill prompts extracted from your memory. When a task matches a skill's domain, apply its 'summary' as behavioral guidance and follow 'methods' steps. Skills are pre-loaded at session start for token efficiency — do not re-derive their patterns."
+  },
+
+  "ide_order": [
+    "cursor",
+    "claude-code",
+    "windsurf",
+    "cline",
+    "copilot",
+    "codex",
+    "kiro",
+    "trae",
+    "zed",
+    "jetbrains",
+    "augment",
+    "antigravity",
+    "openclaw"
+  ],
+  "ides": {
+    "claude-code": {
+      "label": "Claude Code",
+      "rules_file": "CLAUDE.md",
+      "mcp_path": ".mcp.json",
+      "mcp_config_variant": "sse",
+      "strategy": "managed_block",
+      "conflict_policy": "error_on_invalid_markers",
+      "header": "# Project Memory (Awareness MCP)",
+      "preamble_lines": [
+        "> IMPORTANT: These instructions override default behavior. You must follow them exactly."
+      ],
+      "notes_lines": [
+        "## Compliance Check",
+        "Before responding to ANY user request:",
+        "1. Have you called awareness_init yet this session? If not, call it NOW.",
+        "2. Did you just edit a file? Call awareness_record(content=<detailed description>, insights={...}) IMMEDIATELY.",
+        "3. Is the user asking about past work? Call awareness_recall FIRST."
+      ]
+    },
+    "cursor": {
+      "label": "Cursor",
+      "rules_file": ".cursor/rules/awareness.mdc",
+      "mcp_path": ".cursor/mcp.json",
+      "strategy": "managed_file",
+      "conflict_policy": "error_on_unmanaged_file_unless_force",
+      "header": "# Awareness Memory Rules",
+      "frontmatter": {
+        "description": "Awareness cross-session memory integration rules",
+        "globs": "",
+        "alwaysApply": true
+      },
+      "notes_lines": [
+        "## Cursor-Specific Notes",
+        "- Call awareness_init at the start of EVERY new composer/chat session.",
+        "- When using Cursor's edit/apply features, record each apply as a awareness_record.",
+        "- The MCP server is configured in .cursor/mcp.json - memory_id is in the headers."
+      ]
+    },
+    "windsurf": {
+      "label": "Windsurf",
+      "rules_file": ".windsurfrules",
+      "mcp_path": null,
+      "mcp_global_path": "~/.codeium/windsurf/mcp_config.json",
+      "mcp_config_variant": "streamable-http",
+      "strategy": "managed_block",
+      "conflict_policy": "error_on_invalid_markers",
+      "header": "# Awareness Memory Rules",
+      "preamble_lines": [
+        "These rules are MANDATORY for every interaction in this project."
+      ],
+      "notes_lines": [
+        "## Windsurf-Specific Notes",
+        "- Call awareness_init at the start of every new Cascade flow.",
+        "- Record each step of multi-file edits with awareness_record."
+      ]
+    },
+    "cline": {
+      "label": "Cline",
+      "rules_file": ".clinerules",
+      "mcp_path": null,
+      "mcp_config_variant": "sse",
+      "mcp_type_field": "transportType",
+      "strategy": "managed_block",
+      "conflict_policy": "error_on_invalid_markers",
+      "header": "# Awareness Memory Rules",
+      "preamble_lines": [
+        "MANDATORY rules - follow for the entire session."
+      ],
+      "notes_lines": [
+        "## Cline-Specific Notes",
+        "- Call awareness_init when Cline starts a new task.",
+        "- After each tool use (file edit, terminal command), call awareness_record."
+      ]
+    },
+    "copilot": {
+      "label": "VS Code Copilot",
+      "rules_file": ".github/copilot-instructions.md",
+      "mcp_path": ".vscode/mcp.json",
+      "mcp_servers_key": "servers",
+      "mcp_config_variant": "http",
+      "strategy": "managed_block",
+      "conflict_policy": "error_on_invalid_markers",
+      "header": "# Awareness Memory Rules",
+      "preamble_lines": [
+        "MANDATORY repository instructions for VS Code GitHub Copilot."
+      ],
+      "notes_lines": [
+        "## VS Code Copilot Notes",
+        "- Call awareness_init at the start of each new Copilot Chat or agent task.",
+        "- After each file edit, terminal command, decision, or fix, call awareness_record.",
+        "- The MCP server config should live in .vscode/mcp.json."
+      ]
+    },
+    "codex": {
+      "label": "Codex",
+      "rules_file": "AGENTS.md",
+      "mcp_path": null,
+      "mcp_path_toml": ".codex/config.toml",
+      "strategy": "managed_block",
+      "conflict_policy": "error_on_invalid_markers",
+      "header": "# Awareness Memory Integration",
+      "preamble_lines": [
+        "MANDATORY agent policy - follow for every task."
+      ],
+      "notes_lines": [
+        "## Codex-Specific Notes",
+        "- Call awareness_init at task start before reading any files.",
+        "- After each code patch, call awareness_record with the change description."
+      ]
+    },
+    "kiro": {
+      "label": "Kiro",
+      "rules_file": ".kiro/steering/awareness.md",
+      "mcp_path": ".kiro/settings/mcp.json",
+      "strategy": "managed_file",
+      "conflict_policy": "error_on_unmanaged_file_unless_force",
+      "header": "# Awareness Memory Rules",
+      "preamble_lines": [
+        "Steering document — MANDATORY for every Kiro session."
+      ],
+      "notes_lines": [
+        "## Kiro-Specific Notes",
+        "- Call awareness_init at the start of every new Kiro task or spec.",
+        "- After each code edit or spec change, call awareness_record.",
+        "- The MCP server is configured in .kiro/settings/mcp.json."
+      ]
+    },
+    "trae": {
+      "label": "Trae",
+      "rules_file": ".trae/rules/awareness.md",
+      "mcp_path": ".trae/mcp.json",
+      "mcp_config_variant": "sse",
+      "mcp_array_format": true,
+      "strategy": "managed_file",
+      "conflict_policy": "error_on_unmanaged_file_unless_force",
+      "header": "# Awareness Memory Rules",
+      "preamble_lines": [
+        "MANDATORY rules for every Trae session in this project."
+      ],
+      "notes_lines": [
+        "## Trae-Specific Notes",
+        "- Call awareness_init at the start of every new chat or Builder session.",
+        "- After each file edit or terminal command, call awareness_record.",
+        "- The MCP server is configured in .trae/mcp.json at the project root."
+      ]
+    },
+    "zed": {
+      "label": "Zed",
+      "rules_file": ".rules",
+      "mcp_path": null,
+      "strategy": "managed_block",
+      "conflict_policy": "error_on_invalid_markers",
+      "header": "# Awareness Memory Rules",
+      "preamble_lines": [
+        "MANDATORY rules for every Zed Assistant session."
+      ],
+      "notes_lines": [
+        "## Zed-Specific Notes",
+        "- Call awareness_init at the start of every new Assistant thread.",
+        "- After each inline edit or slash command, call awareness_record.",
+        "- MCP server is configured in ~/.config/zed/settings.json under context_servers."
+      ]
+    },
+    "jetbrains": {
+      "label": "JetBrains (Junie)",
+      "rules_file": ".junie/guidelines.md",
+      "mcp_path": ".junie/mcp/mcp.json",
+      "strategy": "managed_block",
+      "conflict_policy": "error_on_invalid_markers",
+      "header": "# Awareness Memory Rules",
+      "preamble_lines": [
+        "MANDATORY guidelines — follow for every Junie task."
+      ],
+      "notes_lines": [
+        "## JetBrains / Junie Notes",
+        "- Call awareness_init at the start of every new Junie task.",
+        "- After each code change, call awareness_record with the change description.",
+        "- The MCP server is configured in .junie/mcp/mcp.json."
+      ]
+    },
+    "augment": {
+      "label": "Augment",
+      "rules_file": ".augment/rules/awareness.md",
+      "mcp_path": null,
+      "mcp_config_variant": "sse",
+      "strategy": "managed_block",
+      "conflict_policy": "error_on_invalid_markers",
+      "header": "# Awareness Memory Rules",
+      "preamble_lines": [
+        "MANDATORY guidelines for every Augment session."
+      ],
+      "notes_lines": [
+        "## Augment-Specific Notes",
+        "- Call awareness_init at the start of every new Augment task.",
+        "- After each code edit or suggestion, call awareness_record.",
+        "- MCP server is configured via Augment Settings Panel or JSON import."
+      ]
+    },
+    "antigravity": {
+      "label": "Google AntiGravity (Jules)",
+      "rules_file": ".antigravity/rules.md",
+      "mcp_path": null,
+      "mcp_global_path": "~/.gemini/antigravity/mcp_config.json",
+      "strategy": "managed_block",
+      "conflict_policy": "error_on_invalid_markers",
+      "header": "# Awareness Memory Rules",
+      "preamble_lines": [
+        "MANDATORY guidelines for every Jules task."
+      ],
+      "notes_lines": [
+        "## AntiGravity / Jules Notes",
+        "- Call awareness_init at the start of every new task or plan.",
+        "- After each code change or plan step, call awareness_record.",
+        "- MCP server is configured in ~/.gemini/antigravity/mcp_config.json or via the MCP Servers menu."
+      ]
+    },
+    "openclaw": {
+      "label": "OpenClaw",
+      "rules_file": null,
+      "mcp_path": null,
+      "strategy": "plugin_config",
+      "notes_lines": [
+        "## OpenClaw Notes",
+        "- OpenClaw uses a plugin-based configuration via ~/.openclaw/openclaw.json.",
+        "- Install the Awareness plugin: openclaw plugins install @awareness-sdk/openclaw-memory",
+        "- MCP tools are exposed through the plugin system, no rules file needed."
+      ]
+    }
+  }
+}