Memory Operations — Trace Skill Skill

Memory Operations — Trace Skill

When to Use

Activate this skill when:

User asks about coding memory, shared notes, or repo context
User wants to store, retrieve, or update knowledge about the codebase
User mentions handoffs, PR notes, architecture decisions, or team knowledge
User asks about canonical memory, team memory, or user memory
User wants to set up a memory backend (Redis or SQL)
User asks about Trace or infynon trace
.infynon/trace/config.toml is detected in the project
User asks about knowledge graph, entity relationships, or how things connect in the repo
User wants to visualize code relationships, file dependencies, or people-to-file mappings
User asks about graph diff, impact analysis, or path finding between entities

Critical Rules

Layer discipline. Always place notes in the correct layer:
- Canonical — architecture decisions, API contracts, config invariants, security constraints, module facts, migration rules
- Team — active caveats, branch notes, handoffs, PR summaries, risky areas, unresolved issues
- User — personal reminders, local observations, unfinished thoughts, task context
Never auto-create canonical notes. Canonical notes are promoted, not auto-written.
Always resolve default user from infynon trace config when --author is not specified.
Every note should track provenance: source commit, status, confidence, updated_at.

Prerequisites

infynon --version

If not installed:

npm install -g infynon

Initialize Trace

# Initialize with repo identity
infynon trace init

# Add a SQL backend (recommended for canonical + team memory)
infynon trace source add-sql team-db \
  --engine sqlite \
  --url sqlite://.infynon/trace/trace.db \
  --user <username> \
  --default

# Or add Redis for fast session-style coordination
infynon trace source add-redis team-redis \
  --url redis://localhost:6379/0 \
  --namespace infynon \
  --user <username>

Command Reference by User Intent

"I want to store a note about the codebase"

# Team-level note (most common)
infynon trace note add <id> \
  --title "Description" \
  --body "Details" \
  --layer team \
  --scope repo

# Branch-specific handoff
infynon trace note add <id> \
  --title "Handoff note" \
  --body "What the next person needs to know" \
  --layer team \
  --scope branch \
  --target feature/my-branch \
  --tags handoff

# PR-linked note
infynon trace note add <id> \
  --title "PR context" \
  --body "Why this change was made" \
  --layer team \
  --scope pr \
  --target 142 \
  --related-pr 142

# File-scoped note
infynon trace note add <id> \
  --title "Watch out" \
  --body "This module has a known race condition" \
  --layer team \
  --scope file \
  --target src/auth.rs \
  --files src/auth.rs \
  --tags caveat,race-condition

# Package note (who introduced a risky dependency)
infynon trace note add <id> \
  --title "chrono added" \
  --body "Added for Trace sync timestamps. Low risk." \
  --layer user \
  --scope package \
  --target chrono

"I want to find relevant notes"

# All canonical memory
infynon trace retrieve --layer canonical --format markdown

# Team notes for current branch
infynon trace retrieve --layer team --scope branch --target <branch-name> --format markdown

# Notes about a specific file
infynon trace retrieve --scope file --target src/auth.rs

# Notes by a specific author
infynon trace retrieve --author alien

# Notes with a specific tag
infynon trace retrieve --tag handoff

# Package notes
infynon trace retrieve --scope package --target chrono

# PR-linked notes
infynon trace retrieve --scope pr --target 142

"I want to update or clean up notes"

# Mark a note as stale
infynon trace note update <id> --status stale

# Update note content
infynon trace note update <id> --title "New title" --body "Updated content"

# Remove a note
infynon trace note remove <id>

# Compact stale and session notes
infynon trace compact

"I want to sync with a remote backend"

# Push local notes to remote
infynon trace sync --direction push

# Pull remote notes locally
infynon trace sync --direction pull

# Bidirectional sync
infynon trace sync --direction both

# Sync with a specific backend
infynon trace sync --source team-db --direction both

"I want to promote a note to canonical"

Canonical notes are never auto-created. The promotion path:

Start as user or team note
Validate against current code state
Confirm the note has been stable (no contradictions across merges)
Create the canonical version

# Step 1: Flag for promotion
infynon trace note update my-note --tags promote,canonical-candidate

# Step 2: After review, create canonical note
infynon trace note add arch-<topic> \
  --title "Architectural decision: ..." \
  --body "Validated across PRs #x, #y. Stable since v0.x.x." \
  --layer canonical \
  --scope repo \
  --tags architecture

# Step 3: Archive the original team note
infynon trace note update my-note --status archived

"I want to set up backends"

# List current backends
infynon trace source list

# Add SQLite (local, good for canonical + team)
infynon trace source add-sql local-db \
  --engine sqlite \
  --url sqlite://.infynon/trace/trace.db \
  --user <username> \
  --default

# Add PostgreSQL (shared team database)
infynon trace source add-sql team-db \
  --engine postgres \
  --url postgres://user:pass@db.example.com:5432/infynon \
  --user <username>

# Add Redis (fast session state)
infynon trace source add-redis session-redis \
  --url redis://localhost:6379/0 \
  --namespace infynon \
  --user <username>

# Set default backend
infynon trace source default team-db

# Remove a backend
infynon trace source remove old-source

# View backend schema
infynon trace schema sql
infynon trace schema redis

Backend Selection Guide

| Use Case | Backend | Why | |----------|---------|-----| | Canonical memory | SQL (SQLite/Postgres) | Durable, auditable, structured queries | | Team memory | SQL or Redis | SQL for history, Redis for live coordination | | User memory | Local files or SQLite | Personal, low overhead | | Session state | Redis | Fast, ephemeral, auto-expiring | | CI/CD integration | SQL (Postgres) | Shared across runners, queryable | | Multi-machine sync | Redis or Postgres | Network-accessible |

Note Scopes

| Scope | Use For | Example Target | |-------|---------|----------------| | repo | Repository-wide facts | current | | branch | Branch-specific context | feature/auth-refresh | | pr | PR-linked notes | 142 | | file | File-specific caveats | src/auth.rs | | user | User-specific notes | alien | | session | Temporary session context | current | | package | Dependency provenance | chrono |

TUI

infynon trace tui

6 Tabs: | Key | Tab | Purpose | |-----|-----|---------| | 1 | Overview | Trace status, config summary, layer counts | | 2 | Sources | Backend list, connection status, default indicator | | 3 | Notes | Browse all notes, filter by layer/scope/status | | 4 | Packages | Package findings with installed_by attribution | | 5 | EditLog | History of note changes | | 6 | Graph | Knowledge graph: entities, edges, visual view, branch switching |

TUI Keys:

Tab / Shift+Tab — navigate fields
Enter — edit field
q — quit
Arrow keys — scroll and navigate
b — switch branch (Graph tab)
a — toggle all-branches view (Graph tab)
B — auto-build graph (Graph tab)
n — new entity/edge (Graph tab)
d — delete entity/edge (Graph tab)

"I want to use the knowledge graph"

The knowledge graph maps entities (files, packages, people, decisions, vulnerabilities) and relationships between them, scoped per branch.

# Auto-build graph from git history and existing notes
infynon trace graph build

# Add entities manually
infynon trace graph entity add alice --kind person
infynon trace graph entity add "POST /login" --kind endpoint --meta method=POST,auth=required
infynon trace graph entity add CVE-2025-1234 --kind vulnerability
infynon trace graph entity add auth-decision --kind decision

# Add on a specific branch
infynon trace graph entity add bob --kind person --branch feature/auth

# Add relationships
infynon trace graph edge add --from alice --to src/auth.rs --relation modified_by --evidence "commit:abc123"
infynon trace graph edge add --from src/auth.rs --to ratatui --relation depends_on --weight 0.9
infynon trace graph edge add --from CVE-2025-1234 --to ratatui --relation exposes

# Query the graph
infynon trace graph show --branch main
infynon trace graph show --kind person
infynon trace graph path CVE-2025-1234 alice
infynon trace graph impact src/auth.rs
infynon trace graph orphans
infynon trace graph diff main feature/auth

# Export / Import
infynon trace graph export --format json -o graph.json
infynon trace graph export --format dot -o graph.dot
infynon trace graph import graph.json --branch imported

# Manage
infynon trace graph entity list --kind person
infynon trace graph edge list --relation modified_by
infynon trace graph entity remove alice
infynon trace graph edge remove <edge-id>

# TUI
infynon trace graph tui
infynon trace graph tui --branch feature/auth

Entity kinds: file, package, person, decision, endpoint, module, pr, branch, note, vulnerability

Relation types: depends_on, introduced_by, modified_by, affects, decided_by, relates_to, supersedes, conflicts_with, documents, exposes, owns

Tips

Use --scope branch for handoffs so they auto-associate with the branch lifecycle
Use --scope pr with --related-pr to link notes to pull requests
Tag notes with promote when they're candidates for canonical promotion
Run infynon trace compact regularly to clean session and stale notes
Use --layer user for personal scratch notes that shouldn't clutter team memory
Canonical memory should be the smallest layer — resist the urge to canonicalize everything
Use infynon trace graph build to auto-populate the graph from git history — it works from day zero
Use infynon trace graph diff main feature/auth to see knowledge divergence before merging
Use infynon trace graph impact <entity> to understand blast radius of changes
Graph data syncs with backends alongside notes — same infynon trace sync command

Agent Skills: Memory Operations — Trace Skill

Install this agent skill to your local

Skill Files