Documentation
¶
Overview ¶
Package knowledge implements bee's per-project on-disk knowledge store.
records are markdown files with a YAML frontmatter header carrying freeform tags, an explicit priority, and an optional expiration. the scanner returns entries cheaply (header only); record bodies are loaded lazily so listings stay fast even on large stores.
Index ¶
- Constants
- func AgeSince(modified time.Time) string
- func Body(path string) (string, error)
- func ExtractTags(ctx context.Context, p llm.Provider, model, userQuery string) ([]string, error)
- func Index() (string, error)
- func ListEntries(dir string) ([]string, error)
- func RebuildIndex(dir string) error
- func StalenessNote(expiresAt time.Time) string
- func StoreDir() (string, error)
- func WriteRecord(dir string, r Record) (string, error)
- type Entry
- type Options
- type Record
Constants ¶
const ( TagPersonal = "personal" TagGuidance = "guidance" TagProject = "project" TagExternal = "external" )
well-known tag names used by the migration shim when converting legacy type-tagged files. callers should treat these as ordinary tag strings — nothing in the store validates against this list.
const DefaultPriority = 3
DefaultPriority is the assumed priority when frontmatter omits the field.
const FrontmatterMaxLines = 30
FrontmatterMaxLines bounds the byte budget for header parsing. anything past this is treated as body.
const IndexFileName = "INDEX.md"
IndexFileName is the rebuilt-on-write index inside StoreDirName. it is excluded from scans so the index entry never appears as a record.
const MaxEntries = 200
MaxEntries caps how many entries ScanStore will return per call. larger stores still load but the tail is dropped after mtime sort.
const MaxResults = 5
MaxResults caps the records Query returns regardless of caller intent.
const StoreDirName = "store"
StoreDirName is the leaf directory bee writes records into.
Variables ¶
This section is empty.
Functions ¶
func AgeSince ¶
AgeSince renders a short natural-language age string for modified. used to head each record in the assembled system prompt.
func ExtractTags ¶
ExtractTags drives a side-channel LLM call to map a free-text query onto 1-3 tag keywords. callers feed the result back into Query via Options. errors degrade quietly to (nil, err) so the agent loop can keep going on the deterministic phase-1 score.
func ListEntries ¶
ListEntries returns every *.md path under dir except the INDEX. callers use it to cheaply count records without firing the parser.
func RebuildIndex ¶
RebuildIndex rewrites INDEX.md as a markdown table sorted by priority desc then name asc. callers run this after each WriteRecord but may also invoke directly to repair an out-of-sync index.
func StalenessNote ¶
StalenessNote returns a one-line warning if the record's expiration has passed. zero-value (never-expires) records always return "".
func StoreDir ¶
StoreDir returns the directory bee will read/write knowledge records to.
resolution order:
- $BEE_STORE_DIR (must be absolute + non-near-root)
- if cwd is inside a git repo: ~/.bee/store/<slug-of-git-root>
- ~/.bee/store
when only the legacy path exists ( ~/.bee/projects/<slug>/memory or ~/.bee/memory ) StoreDir returns it as-is so existing data still loads.
Types ¶
type Entry ¶
type Entry struct {
Path string `json:"path"`
Name string `json:"name"`
Description string `json:"description"`
Tags []string `json:"tags,omitempty"`
Priority int `json:"priority"`
ExpiresAt time.Time `json:"expires_at,omitempty"`
Modified time.Time `json:"modified"`
}
Entry is the lightweight header view of a record file: just the parsed frontmatter plus stat metadata. body fetched separately via Body().
func ReadEntry ¶
ReadEntry stats and parses the frontmatter of one file into an Entry. missing or unparseable frontmatter degrades to a name-only record so the caller still sees the file in listings.
func ScanStore ¶
ScanStore walks dir for *.md files, parses each frontmatter in parallel, and returns entries sorted mtime desc, capped at MaxEntries. INDEX.md is excluded. a missing dir returns (nil, nil) so callers can fall through. repeat calls return a cached slice when the dir mtime is unchanged.
type Options ¶
type Options struct {
// HintTags are query-derived tags merged with the user-supplied ones.
// populate from a side query when you want phase-2 hint extraction.
HintTags []string
// Now overrides the wall clock for testing. zero = time.Now().
Now time.Time
// Exclude paths that already surfaced this turn so the budget goes to
// fresh candidates.
Exclude map[string]bool
}
Options tunes query behavior. zero values pick sensible defaults.
type Record ¶
Record is the full file: header plus body.
func Query ¶
Query scores every entry in dir against the user's plain-text query and returns the top-N records (header + body). scoring is deterministic and purely structural — no LLM call is made. Callers wanting phase-2 hint extraction supply Options.HintTags from a side query.
returns (nil, nil) for missing or empty stores so callers can fall through without first stat'ing.
Source Files