@fyso/awareness-framework 0.2.0 → 0.3.1

package/src/memory-candidates.js

@@ -0,0 +1,82 @@
+import { normalizeSearchText } from './text.js';
+
+export function activeMemoryCandidates(content) {
+  const prunedTexts = prunedMemoryCandidateTexts(content);
+  return parseMemoryCandidates(content).filter((candidate) => !prunedTexts.has(normalizeMemoryCandidateText(candidate.text)));
+}
+
+export function isPrunedMemoryText(content, text) {
+  return prunedMemoryCandidateTexts(content).has(normalizeMemoryCandidateText(text));
+}
+
+export function memoryCandidateExists(content, text, evidence) {
+  const candidates = extractMarkdownSection(content, 'Promotion Candidates');
+  return candidates.split('\n').some((line) => line.includes(`: ${text} (evidence: ${evidence})`));
+}
+
+export function memoryCandidateTextExists(content, text) {
+  const key = normalizeMemoryCandidateText(text);
+  return parseMemoryCandidates(content).some((candidate) => normalizeMemoryCandidateText(candidate.text) === key);
+}
+
+export function repeatedMemoryCandidateSuggestions(content, minCount) {
+  const grouped = new Map();
+  for (const candidate of activeMemoryCandidates(content)) {
+    const key = normalizeMemoryCandidateText(candidate.text);
+    const group = grouped.get(key) || { text: candidate.text, count: 0, evidence: [] };
+    group.count += 1;
+    group.evidence.push(candidate.evidence);
+    grouped.set(key, group);
+  }
+
+  return [...grouped.values()]
+    .filter((group) => group.count >= minCount)
+    .map((group) => ({
+      text: group.text,
+      count: group.count,
+      evidence: [...new Set(group.evidence)].join('; '),
+    }))
+    .sort((left, right) => right.count - left.count || left.text.localeCompare(right.text));
+}
+
+function parseMemoryCandidates(content) {
+  const candidates = [];
+  const candidatePattern = /^- \d{4}-\d{2}-\d{2}: (.+) \(evidence: (.+)\)$/;
+  for (const rawLine of extractMarkdownSection(content, 'Promotion Candidates').split('\n')) {
+    const match = candidatePattern.exec(rawLine.trim());
+    if (!match) continue;
+    candidates.push({
+      line: match[0],
+      text: match[1],
+      evidence: match[2],
+    });
+  }
+  return candidates;
+}
+
+function prunedMemoryCandidateTexts(content) {
+  const pruned = new Set();
+  const prunedPattern = /^- \d{4}-\d{2}-\d{2}: (.+) \(reason: .+; evidence: .+\)$/;
+  for (const rawLine of extractMarkdownSection(content, 'Pruned Or Revised').split('\n')) {
+    const match = prunedPattern.exec(rawLine.trim());
+    if (match) pruned.add(normalizeMemoryCandidateText(match[1]));
+  }
+  return pruned;
+}
+
+function normalizeMemoryCandidateText(text) {
+  return normalizeSearchText(text);
+}
+
+function extractMarkdownSection(content, section) {
+  const lines = content.split('\n');
+  const start = lines.findIndex((line) => line.trimEnd() === `## ${section}`);
+  if (start === -1) return '';
+
+  const body = [];
+  for (const line of lines.slice(start + 1)) {
+    if (line.startsWith('## ')) break;
+    body.push(line);
+  }
+  return body.join('\n').replace(/^\n/, '');
+}

package/src/text.js

@@ -0,0 +1,35 @@
+const RECALL_ALIASES = {
+  memoria: ['memory'],
+  memorias: ['memory'],
+  memory: ['memoria', 'memorias'],
+  user: ['usuario', 'usuarios'],
+  users: ['usuario', 'usuarios'],
+  usuario: ['user', 'users'],
+  usuarios: ['user', 'users'],
+};
+
+export function normalizeSearchText(text) {
+  return String(text)
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function recallTermGroups(query) {
+  return normalizeSearchText(query)
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((term) => new Set([term, ...recallTokenVariants(term), ...(RECALL_ALIASES[term] || [])]))
+    .map((terms) => [...terms].filter(Boolean))
+    .filter((terms, index, groups) => groups.findIndex((group) => group[0] === terms[0]) === index);
+}
+
+function recallTokenVariants(term) {
+  const variants = [];
+  if (term.endsWith('es') && term.length > 4) variants.push(term.slice(0, -2));
+  if (term.endsWith('s') && term.length > 3) variants.push(term.slice(0, -1));
+  return variants;
+}

package/templates/agent-instructions.md

@@ -6,7 +6,7 @@ You operate in a multi-task, multi-agent environment. Before doing work, load th
 
 - Awareness board: `~/.agents/awareness/current.md`
 - Daily worklog: `~/.agents/worklog/YYYY-MM-DD.md`
-- Optional durable memory: `~/.agents/memory/`
+- Durable memory and review candidates: `~/.agents/memory/`
 - Optional narrow user memory: `~/.agents/memory/users/<user>.md` or scoped channel equivalent
 - Optional evaluation notes: `~/.agents/evaluations/YYYY-MM-DD.md`
 - Runtime hook and scheduler events: `~/.agents/runtime/`
@@ -20,18 +20,27 @@ You operate in a multi-task, multi-agent environment. Before doing work, load th
 5. When concrete progress happens, append to the daily worklog.
 6. When state changes, update the awareness board.
 7. Before handoff, run `awareness handoff` if available; otherwise make the awareness board reflect the exact current state and append a final worklog entry.
-8. At end of day, prepare a task-grouped summary for human review.
-9. Treat hook and scheduler runtime events as diagnostics only; they do not replace task worklog entries.
-10. For multi-user channels, keep context scoped by channel and store only narrow user facts in `memory/users/<user>.md`.
+8. When evaluation or handoff exposes repeated friction, review memory candidates with `awareness memory candidates` or `awareness memory review`.
+9. At end of day, prepare a task-grouped summary for human review, including memory candidates and pattern suggestions.
+10. Treat hook and scheduler runtime events as diagnostics only; they do not replace task worklog entries.
+11. For multi-user channels, keep context scoped by channel and store only narrow user facts in `memory/users/<user>.md`.
 
 ## Rules
 
 - Keep the worklog append-only.
 - Do not invent task IDs.
 - Record evidence: paths, commands, test results, commits, PRs, deployments, blockers.
-- Prefer CLI maintenance commands (`awareness focus`, `awareness log`, `awareness handoff`, `awareness evaluate`) when available.
+- Prefer CLI maintenance commands (`awareness focus`, `awareness log`, `awareness handoff`, `awareness evaluate`, `awareness memory candidates`, `awareness memory review`) when available.
+- Let evaluations and schedules record promotion candidates, but promote durable memory only with explicit evidence through `awareness memory promote`.
+- Promote repeated candidates as `pattern` only after `awareness memory review` or equivalent evidence shows repetition.
+- Promote direct user preferences promptly when they affect future collaboration.
 - Use `awareness user note` only for short, evidence-backed participant facts such as nicknames, repeated questions, topics, or explicit preferences.
-- Use `awareness hook run` and `awareness schedule run` only for low-noise maintenance; do not let them post externally or promote long-term memory silently.
+- Use `awareness hook run` and `awareness schedule run` only for low-noise maintenance; do not let them post externally or silently promote long-term memory.
 - Keep private state out of version control.
 - Ask before posting worklogs, comments, status changes, or summaries to external systems.
 - Propose framework improvements through reviewed changes, not hidden local edits.
+
+- Use `awareness remember` for explicit observations that should enter memory review.
+- Use `awareness recall QUERY` before repeating uncertain or previously solved work.
+- Use `awareness forget --text TEXT --reason REASON --evidence EVIDENCE` when memory is stale, wrong, or superseded.
+- Use `awareness improve` after material work or process friction to run evaluation plus memory review.

package/templates/cli-wrapper.md

@@ -6,6 +6,6 @@ Read and follow the canonical private protocol at:
 
 If your CLI does not expand `@` imports automatically, open that file explicitly before starting work.
 
-Treat imported awareness files as session-start snapshots. If the Awareness CLI is available, run `awareness status` or `awareness check` at session start, `awareness refresh` when parallel work may have changed state, and `awareness handoff` before returning control.
+Treat imported awareness files as session-start snapshots. If the Awareness CLI is available, run `awareness status` or `awareness check` at session start, `awareness refresh` when parallel work may have changed state, `awareness memory review` when evaluating repeated candidates, and `awareness handoff` before returning control.
 
 Keep this wrapper small. The framework should live in versioned methodology docs, and live operational state should stay private.

package/templates/end-of-day-summary.md

@@ -25,3 +25,11 @@
 ## Methodology Observations
 
 - Anything that made the awareness or worklog process better or worse
+
+## Memory Review
+
+- New promotion candidates:
+- Repeated candidates or suggested patterns:
+- Promotions made:
+- Needs user confirmation:
+- Candidates to prune or leave short-term:

package/templates/evaluation-note.md

@@ -22,6 +22,9 @@
 
 - Short-term observations to keep short-term:
 - Long-term memory candidates:
+- Repeated candidates from `awareness memory review`:
+- Suggested pattern promotions:
+- Promotion command and evidence:
 - Memory to prune or revise:
 - User confirmation needed:
 
@@ -29,7 +32,7 @@
 
 - Awareness cleanup:
 - Worklog correction:
-- Long-term memory promotion:
+- Long-term memory promotion, candidate, or prune decision:
 - Personality update:
 - Framework PR candidate:
 

package/templates/memory-long-term.md

@@ -3,7 +3,7 @@
 - Updated: never
 - Scope: Local private state; do not commit
 
-This file stores durable, curated memory that improves future collaboration. Add entries only when they are user-confirmed, repeated, or operationally important.
+This file stores durable, curated memory that improves future collaboration. Evaluations may add promotion candidates automatically, but durable entries should be promoted only when they are user-confirmed, repeated, or operationally important.
 
 ## Preferences
 
@@ -25,6 +25,19 @@ This file stores durable, curated memory that improves future collaboration. Add
 
 - None yet.
 
+## Review Notes
+
+- Use `awareness memory candidates` to inspect raw candidates.
+- Use `awareness memory review` to surface repeated candidates that may deserve promotion as `Patterns`.
+- Use `awareness memory promote --kind preference|pattern|project|review --text TEXT --evidence EVIDENCE` after review.
+- Repeated candidates may share the same text with distinct evidence; do not collapse them before review.
+
+## Event Log
+
+- Append-only audit history: `memory/events.jsonl`
+- Markdown sections are readable projections.
+- Do not hand-edit event history.
+
 ## Pruned Or Revised
 
 - None yet.
@@ -35,3 +48,4 @@ This file stores durable, curated memory that improves future collaboration. Add
 - Do not promote one-off guesses without repeated evidence.
 - Direct user instructions override memory.
 - Remove or soften stale memory.
+- Keep promotion evidence concise and linkable.