files

package
v0.52.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package files is the built-in memory backend: per scope one MEMORY.md index plus one Markdown file per entry. It needs nothing but the standard library, so memory works out of the box.

Two layouts are supported:

  • DirLayout{Dir}: index <Dir>/MEMORY.md, entries <Dir>/<id>.md; used for user memory under <SUGA_HOME>/memory/user and for project memory without a repository MEMORY.md, under <SUGA_HOME>/projects/<key>/memory.
  • RepoLayout{Root}: index <Root>/MEMORY.md, entries <Root>/.suga/memory/<id>.md (project memory kept in the repository).

Index lines have the form "- [Title](relative/path.md) — kind". Lines that do not match (headings, prose, other lists) are hand-written and preserved verbatim at their position; they are read-only for the backend. New entries are appended at the end of MEMORY.md.

All file access goes through os.Root, so ids and symlinks cannot reach outside the layout root. Directories are created 0700, files 0600, and every file is replaced atomically (temp file + rename). A Store serializes its own writes; concurrent writers in other processes are not coordinated (last index write wins).

Index

Constants

View Source
const Name = "files"

Name is the backend name reported by BackendName.

Variables

This section is empty.

Functions

This section is empty.

Types

type DirLayout

type DirLayout struct{ Dir string }

DirLayout keeps MEMORY.md and <id>.md files side by side in Dir. Dir is created on the first write.

type Layout

type Layout interface {
	// contains filtered or unexported methods
}

Layout places a scope's index and entry files. It is implemented by DirLayout and RepoLayout only.

type Option

type Option func(*Store)

Option configures a Store.

func WithClock

func WithClock(now func() time.Time) Option

WithClock sets the time source for Updated (tests).

type RepoLayout

type RepoLayout struct{ Root string }

RepoLayout keeps MEMORY.md at the repository root and entries under .suga/memory/. Root must already exist; it is never created.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store implements memory.Store over files.

func New

func New(layouts map[memory.Scope]Layout, opts ...Option) (*Store, error)

New builds a Store with one layout per scope (exact Scope match, e.g. memory.UserScope() and memory.ProjectScope("<key>")). Layout roots must be absolute paths.

func (*Store) BackendName

func (s *Store) BackendName() string

BackendName implements memory.Named.

func (*Store) Entries

func (s *Store) Entries(_ context.Context, sc memory.Scope) ([]memory.Entry, error)

Entries enumerates readable entry files using the same id and root safety rules as Search. Missing layouts are empty; unreadable or escaping entries are skipped so one bad file cannot hide the rest of the scope.

func (*Store) Get

func (s *Store) Get(_ context.Context, sc memory.Scope, id string) (memory.Entry, error)

Get implements memory.Store. Missing title or kind in the entry file fall back to the index line.

func (*Store) Index

func (s *Store) Index(_ context.Context, sc memory.Scope) (memory.Index, error)

Index implements memory.Store. A missing layout root or MEMORY.md is an empty index.

func (*Store) Search

func (s *Store) Search(ctx context.Context, sc memory.Scope, q string, limit int) ([]memory.Hit, error)

Search implements memory.Store: every entry file is scanned and matched case-insensitively against all whitespace-separated terms of q (AND) in its title and body. Hits are ordered by Updated (newest first), then id.

func (*Store) SetSummary

func (s *Store) SetSummary(_ context.Context, sc memory.Scope, id, summary string) error

SetSummary implements memory.Summarizer: only the MEMORY.md line changes, the entry file keeps its body untouched. An empty summary removes the summary from the line (back to the old format).

func (*Store) Write

func (s *Store) Write(_ context.Context, sc memory.Scope, op memory.Op) (memory.Entry, error)

Write implements memory.Store: the entry file is written first, then the index, so a crash leaves at most an unlisted file, never a dangling line.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL