memory

Documentation

Overview

Package memory provides the per-workspace iterion memory tree at ~/.iterion/projects/<encoded-workdir>/memory/<scope>/.

Index

• func LegacyBotRef(memBase, scope string) knowledge.SpaceRef
• func ProjectKey(memBase string) string
• func ResolveSpaceRef(vis knowledge.Visibility, name, botOverride, userOverride string, ...) knowledge.SpaceRef
• func ValidateScopeName(scope string) error
• func WorkspaceMemoryDir(workDir string) string
• func WorkspaceScratchDir(workDir string) string
• type AutoloadEntry
• type FSStore
  • func DefaultFSStore() *FSStore
  • func (s *FSStore) Autoload(_ context.Context, ref knowledge.SpaceRef, patterns []string) ([]knowledge.AutoloadEntry, error)
  • func (s *FSStore) BuildIndex(_ context.Context, ref knowledge.SpaceRef) ([]knowledge.IndexEntry, error)
  • func (s *FSStore) DeleteDocument(_ context.Context, ref knowledge.SpaceRef, path string) error
  • func (s *FSStore) ListDocuments(_ context.Context, ref knowledge.SpaceRef, dir string) ([]knowledge.DocumentMeta, error)
  • func (s *FSStore) ReadDocument(_ context.Context, ref knowledge.SpaceRef, path string) (knowledge.Document, error)
  • func (s *FSStore) Root(ref knowledge.SpaceRef) (string, error)
  • func (s *FSStore) UsageBytes(_ context.Context, ref knowledge.SpaceRef) (int64, int64, error)
  • func (s *FSStore) WriteDocument(_ context.Context, ref knowledge.SpaceRef, in knowledge.DocumentInput) (knowledge.DocumentMeta, error)
• type IndexEntry
• type Scope
  • func OpenScope(workDir, scope string) (*Scope, error)
  • func (s *Scope) Autoload(patterns []string) ([]AutoloadEntry, error)
  • func (s *Scope) BuildIndex() ([]IndexEntry, error)
  • func (s *Scope) List(relDir string) ([]string, error)
  • func (s *Scope) Read(rel string) ([]byte, error)
  • func (s *Scope) Resolve(rel string) (string, error)
  • func (s *Scope) Root() string
  • func (s *Scope) Write(rel string, content []byte) error
• type SpaceRefInputs

Functions

func LegacyBotRef

func LegacyBotRef(memBase, scope string) knowledge.SpaceRef

LegacyBotRef builds the SpaceRef a legacy `memory: scope:` block resolves to: an explicit project-visibility space keyed by the encoded project key of memBase (the run workDir, or the repo root when project_root is set). The resolved on-disk path is identical to the pre-knowledge WorkspaceMemoryDir(memBase)/<scope> layout, so existing local bots see the same files without masquerading as a structured bot-qualified space.

func ProjectKey

func ProjectKey(memBase string) string

ProjectKey encodes a memory base dir (run workdir or repo root) into the stable, filesystem-safe project key used in the on-disk layout.

func ResolveSpaceRef

func ResolveSpaceRef(vis knowledge.Visibility, name, botOverride, userOverride string, in SpaceRefInputs) knowledge.SpaceRef

ResolveSpaceRef builds a knowledge.SpaceRef from a DSL-declared memory space (visibility + name + optional bot/user overrides) and the run's resolved identity. Fields a visibility doesn't need stay empty (the FS adapter maps an empty tenant/user to "local").

func ValidateScopeName

func ValidateScopeName(scope string) error

ValidateScopeName rejects scope names that contain path separators, are empty, or attempt traversal. Names must be a single folder segment.

func WorkspaceMemoryDir

func WorkspaceMemoryDir(workDir string) string

WorkspaceMemoryDir returns the per-workspace memory root for the given working directory. Reuses the same encoder + home resolver as the run store so the memory tree sits next to the run state. Returns "" when workDir is empty.

func WorkspaceScratchDir

func WorkspaceScratchDir(workDir string) string

WorkspaceScratchDir returns the per-workspace scratch root, a sibling of WorkspaceMemoryDir at ~/.iterion/projects/<encoded-workdir>/scratch/. It is the home for OUT-OF-TREE working files a bot must not leave in the target repo (e.g. a chunked-review's per-chunk diffs) — keyed off the repo root like the memory tree, and the SAME host path is bind-mounted inside the sandbox (~/.iterion auto-mount), so it resolves in both modes without remapping. Returns "" when workDir is empty.

Types

type AutoloadEntry

type AutoloadEntry struct {
	Path    string // relative to scope root
	Content []byte
}

AutoloadEntry is one file's worth of autoloaded memory content.

type FSStore

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

FSStore is the local-filesystem implementation of knowledge.MemoryStore. It hosts spaces under the global iterion data dir and reuses the path-clamped Scope primitive for all document IO, so the security guarantees (no "../" or absolute escapes) are shared with the legacy scope API.

func DefaultFSStore

func DefaultFSStore() *FSStore

DefaultFSStore returns an FSStore rooted at the global iterion data dir, resolved lazily on each use so a test's ITERION_HOME override (or any runtime change) is honoured.

func (*FSStore) Autoload

func (s *FSStore) Autoload(_ context.Context, ref knowledge.SpaceRef, patterns []string) ([]knowledge.AutoloadEntry, error)

Autoload returns the full content of documents matching the patterns.

func (*FSStore) BuildIndex

func (s *FSStore) BuildIndex(_ context.Context, ref knowledge.SpaceRef) ([]knowledge.IndexEntry, error)

BuildIndex returns one IndexEntry per Markdown document in the space.

func (*FSStore) DeleteDocument

func (s *FSStore) DeleteDocument(_ context.Context, ref knowledge.SpaceRef, path string) error

DeleteDocument removes a document (no-op if absent) and credits its bytes back to the per-space and aggregate counters.

func (*FSStore) ListDocuments

func (s *FSStore) ListDocuments(_ context.Context, ref knowledge.SpaceRef, dir string) ([]knowledge.DocumentMeta, error)

ListDocuments enumerates files directly under the space-relative dir.

func (*FSStore) ReadDocument

func (s *FSStore) ReadDocument(_ context.Context, ref knowledge.SpaceRef, path string) (knowledge.Document, error)

ReadDocument returns a document's metadata + content. A missing document returns an error satisfying errors.Is(err, ErrDocNotFound).

func (*FSStore) Root

func (s *FSStore) Root(ref knowledge.SpaceRef) (string, error)

Root returns the space's absolute on-disk path.

func (*FSStore) UsageBytes

func (s *FSStore) UsageBytes(_ context.Context, ref knowledge.SpaceRef) (int64, int64, error)

UsageBytes returns the space's tracked usage and its effective per-space quota (explicit override, else env/default for the visibility). Bytes written through the legacy Scope API (or before this adapter) are not counted — quota gates new growth, not history.

func (*FSStore) WriteDocument

func (s *FSStore) WriteDocument(_ context.Context, ref knowledge.SpaceRef, in knowledge.DocumentInput) (knowledge.DocumentMeta, error)

WriteDocument creates or replaces a document and returns its metadata. It enforces the per-document size cap and both the per-space and org-aggregate quota ceilings BEFORE committing bytes — an over-quota write returns a *knowledge.QuotaError and never lands on disk. Counters are updated only after the write succeeds, under the global quota lock, so concurrent writers stay consistent.

type IndexEntry

type IndexEntry struct {
	Path        string
	Title       string
	Description string
	Tags        []string
}

IndexEntry summarises one Markdown file in a scope.

type Scope

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

Scope is a sandboxed view of a single feature subfolder. All read/write/list ops are path-clamped to the scope's root — callers cannot escape via "../" or absolute paths.

func OpenScope

func OpenScope(workDir, scope string) (*Scope, error)

OpenScope returns the scope subfolder under the workspace memory root, validating the scope name first.

func (*Scope) Autoload

func (s *Scope) Autoload(patterns []string) ([]AutoloadEntry, error)

Autoload reads every file matching one of the given relative glob patterns under the scope. Returns a slice of (path, content) pairs in deterministic (lexicographic) order, suitable for prepending to a system prompt or compaction injection. Missing files are silently skipped. Errors only surface for path-escape attempts or unreadable files that exist.

Returns an empty slice when patterns is empty — the auto-index (BuildIndex) covers the "what exists in the scope" question, so Autoload is reserved for files whose FULL content must always be in the system prompt (e.g. CONTEXT_BRIEF.md).

func (*Scope) BuildIndex

func (s *Scope) BuildIndex() ([]IndexEntry, error)

BuildIndex walks the scope recursively, collecting one IndexEntry per Markdown file. Lexicographic by path.

func (*Scope) List

func (s *Scope) List(relDir string) ([]string, error)

List enumerates files (not directories) under the scope-relative directory, returning paths relative to the scope root. Order is filesystem-defined. Missing directories return an empty slice without error so callers can use it as a probe.

func (*Scope) Read

func (s *Scope) Read(rel string) ([]byte, error)

Read returns the contents of the file at the scope-relative path. Returns os.ErrNotExist when the file is absent.

func (*Scope) Resolve

func (s *Scope) Resolve(rel string) (string, error)

Resolve translates a scope-relative path to an absolute one, rejecting any path that escapes the scope root. Empty `rel` returns the scope root itself.

func (*Scope) Root

func (s *Scope) Root() string

Root returns the absolute path of this scope's folder.

func (*Scope) Write

func (s *Scope) Write(rel string, content []byte) error

Write replaces the file at the scope-relative path with the given content, creating parent directories as needed.

type SpaceRefInputs

type SpaceRefInputs struct {
	TenantID  string // org tenant ("" → local)
	UserID    string // current operator/user
	ProjectID string // encoded project key (store.EncodeWorkDirKey)
	BotID     string // launching bot id
}

SpaceRefInputs are the per-run identity values used to resolve a structured memory space to a concrete SpaceRef.