Memory System

ultrasync's memory system stores context, decisions, and findings that persist across coding sessions. Instead of losing valuable insights when you close your editor, memories are indexed and retrievable whenever you need them.

What to Store as Memories

Memories work best for capturing insights that would otherwise be lost:

• Design decisions - Why you chose a particular architecture
• Constraints - Limitations you discovered during implementation
• Debugging findings - Root causes of tricky bugs
• Pitfalls - Gotchas that future-you should know about
• Assumptions - Things you assumed that affect the code
• Tradeoffs - Compromises made and their rationale

Writing Memories

Basic Memory

Store a simple text memory:

memory_write("Using Redis for session storage because we need
cross-instance sharing in the load-balanced setup")

Structured Memory

Add taxonomy for better organization and retrieval:

memory_write_structured(
  text="Using Redis for session storage - cross-instance sharing needed",
  task="task:implement_feature",
  insights=["insight:decision", "insight:constraint"],
  context=["context:backend", "context:auth"]
)

Taxonomy Categories

Tasks:

• task:debug - Debugging sessions
• task:refactor - Code refactoring
• task:implement_feature - New feature work

Insights:

• insight:decision - Design or implementation decisions
• insight:constraint - Limitations or requirements
• insight:tradeoff - Accepted compromises
• insight:pitfall - Gotchas or common mistakes
• insight:assumption - Assumptions affecting implementation

Contexts:

• context:frontend - Frontend code
• context:backend - Backend/server code
• context:auth - Authentication/authorization
• context:api - API design
• context:data - Database/data layer

Searching Memories

Semantic Search

Find memories by meaning:

memory_search("authentication decisions")
memory_search("why we chose this database schema")

Structured Search

Filter by taxonomy:

memory_search_structured(
  query="caching",
  task="task:debug",
  insights=["insight:decision"]
)

Automatic Recall

When using search(), relevant memories are automatically included in results. If you previously stored context about a file or concept, it surfaces alongside code results.

When Memories Are Retrieved

ultrasync automatically searches memories when:

• Starting a new task (query describes the goal)
• Beginning debug sessions (query matches error/symptom)
• Working on files you've touched before
• You reference prior work ("remember when", "we discussed")
• Before making significant implementation choices

Sharing Memories

By default, memories are personal. To share with your team:

share_memory("mem:abc123")

Shared memories become visible to all team members working on the same repository (requires team sync to be enabled).

Memory Lifecycle

1. Created - Stored locally with embeddings generated
2. Indexed - Available for semantic search
3. Retrieved - Surfaced when relevant to current work
4. Shared (optional) - Synced to team members

Memories persist indefinitely in your local .ultrasync/ directory. With team sync enabled, shared memories are also stored on the sync server.