Documentation
¶
Overview ¶
Package sync implements git-friendly memory synchronization for Engram.
Instead of a single large JSON file, memories are stored as compressed JSONL chunks with a manifest index. This design:
- Avoids git merge conflicts (each sync creates a NEW chunk, never modifies old ones)
- Keeps files small (each chunk is gzipped JSONL)
- Tracks what's been imported via chunk IDs (no duplicates)
- Works for teams (multiple devs create independent chunks)
Directory structure:
.engram/ ├── manifest.json ← index of all chunks (small, mergeable) ├── chunks/ │ ├── a3f8c1d2.jsonl.gz ← chunk 1 (compressed) │ ├── b7d2e4f1.jsonl.gz ← chunk 2 │ └── ... └── engram.db ← local working DB (gitignored)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetUsername ¶
func GetUsername() string
GetUsername returns the current username for chunk attribution.
func ManifestSummary ¶
ManifestSummary returns a human-readable summary of the manifest.
Types ¶
type ChunkData ¶
type ChunkData struct {
Sessions []store.Session `json:"sessions"`
Observations []store.Observation `json:"observations"`
Prompts []store.Prompt `json:"prompts"`
}
ChunkData is the content of a single chunk file (JSONL entries).
type ChunkEntry ¶
type ChunkEntry struct {
ID string `json:"id"` // SHA-256 hash prefix (8 chars) of content
CreatedBy string `json:"created_by"` // Username or machine identifier
CreatedAt string `json:"created_at"` // ISO timestamp
Sessions int `json:"sessions"` // Number of sessions in chunk
Memories int `json:"memories"` // Number of observations in chunk
Prompts int `json:"prompts"` // Number of prompts in chunk
}
ChunkEntry describes a single chunk in the manifest.
type ImportResult ¶
type ImportResult struct {
ChunksImported int `json:"chunks_imported"`
ChunksSkipped int `json:"chunks_skipped"` // Already imported
SessionsImported int `json:"sessions_imported"`
ObservationsImported int `json:"observations_imported"`
PromptsImported int `json:"prompts_imported"`
}
ImportResult is returned after importing chunks.
type Manifest ¶
type Manifest struct {
Version int `json:"version"`
Chunks []ChunkEntry `json:"chunks"`
}
Manifest is the index file that lists all chunks. This is the only file git needs to diff/merge — it's small and append-only.
type SyncResult ¶
type SyncResult struct {
ChunkID string `json:"chunk_id,omitempty"`
SessionsExported int `json:"sessions_exported"`
ObservationsExported int `json:"observations_exported"`
PromptsExported int `json:"prompts_exported"`
IsEmpty bool `json:"is_empty"` // true if nothing new to sync
}
SyncResult is returned after a sync operation.
type Syncer ¶
type Syncer struct {
// contains filtered or unexported fields
}
Syncer handles exporting and importing memory chunks.
func (*Syncer) Export ¶
func (sy *Syncer) Export(createdBy string, project string) (*SyncResult, error)
Export creates a new chunk with memories not yet in any chunk. It reads the manifest to know what's already exported, then creates a new chunk with only the new data.
func (*Syncer) Import ¶
func (sy *Syncer) Import() (*ImportResult, error)
Import reads the manifest and imports any chunks not yet in the local DB.
Source Files