Waggle project memory

Waggle project memory

Treat Waggle as memory owned by the project, not as a transcript archive or generic personal chat memory.

Establish a stable scope

Before the first Waggle call in a task, choose one stable project value:

1. Prefer the repository's canonical remote identity without credentials or a trailing .git, such as github.com/acme/api.
2. If there is no remote, use the canonical absolute Git root path.
3. Outside Git, use the canonical absolute workspace path.

Reuse that value across sessions. Do not use only a directory basename because unrelated repositories can share it. Pass agent_id: "codex" and the current task/session identifier when one is available. Never mix remembered context from a different project into the answer.

Retrieve selectively

• At the beginning of a new task that involves meaningful project work, call prime_context once with the narrowest known scope.
• Skip priming for greetings, trivial formatting, or questions fully answerable from the current prompt with no project-history dependency.
• Before answering anything that may depend on earlier decisions, preferences, constraints, failed attempts, bugs, experiments, unresolved questions, or project state, call query_graph with the stable project scope. Start with max_nodes: 10, max_depth: 1, and retrieval_mode: "hybrid".
• Use get_related when a returned node ID needs graph context, and graph_diff when the user asks what changed.
• Treat retrieved memories as historical evidence, not current repository truth. Verify changeable facts against the working tree. If retrieval is empty or conflicts with current evidence, say so and do not invent history.

Store durable knowledge only

Use this threshold for every write:

Store information when forgetting it would likely cause duplicated work, a wrong future decision, or violation of an established constraint. Do not store something merely because it happened.

After a completed turn, call observe_conversation only when the turn crosses that threshold and contains durable project knowledge, such as:

• a decision and its rationale;
• a stable requirement, constraint, dependency, or compatibility promise;
• a user correction or durable project preference;
• the diagnosed cause and verified fix for a bug;
• a failed approach worth avoiding and why it failed;
• a benchmark or experiment result with enough context to interpret it;
• an unresolved problem or concrete next step that should survive the session.

Pass the actual completed user_message, the final assistant_response, and the same project, agent, and session scope used for retrieval.