/** * Learning stores - storage backends for each learning capability. * * Python parity: praisonaiagents/memory/learn/stores.py * * Each store owns one kind of learning data (stores.py:4-11): * - PersonaStore: user preferences and profile * - InsightStore: observations and learnings * - ThreadStore: session/conversation context * - PatternStore: reusable knowledge patterns * - DecisionStore: decision logging * - FeedbackStore: outcome signals * - ImprovementStore: self-improvement proposals * * Persistence: `BaseStore` keeps entries in memory and writes them as one * JSON object (`{ [id]: entryDict }`) either to a file (Python * `BaseJSONStore`, storage/base.py:119-160) or through a pluggable * key/value backend (`LearnStorageBackend`, Python `StorageBackendProtocol`). * * Backends ported here: * - FILE: JSON on disk, fully implemented (the default). * - SQLITE: `SQLiteLearnBackend`, same table shape as Python * `storage/backends.py:160-300` (`SQLiteBackend`), driven by the optional * `better-sqlite3` package; the constructor throws * {@link LearnBackendNotAvailableError} when the driver is missing. * - REDIS / MONGODB: constructors that throw {@link LearnBackendNotAvailableError}. * Python does the same in spirit - `praisonaiagents` has no Redis/Mongo * backend of its own and raises `ImportError` from * `storage/backends.py:337-380` unless the `praisonai` package is installed. */ import { type LearnEntryData, type LearnProtocol } from './protocols'; /** * PraisonAI data directory. * Python parity: praisonaiagents/paths.py:126-136 (`get_data_dir`) - the * priority order is `PRAISONAI_HOME`, existing `~/.praisonai`, legacy * `~/.praison`, `$XDG_DATA_HOME/praisonai`, then `~/.praisonai`. */ export declare function getDataDir(): string; /** * Directory holding the learning stores (`/learn`). * Python parity: praisonaiagents/paths.py:342-349 (`get_learn_dir`) */ export declare function getLearnDir(): string; /** Constructor input for {@link LearnEntry} (camelCase mirror of the dataclass fields). */ export interface LearnEntryInit { id: string; content: string; metadata?: Record; createdAt?: string; updatedAt?: string; useCount?: number; lastUsed?: string | null; } /** * Base entry for all learning stores. * Python parity: praisonaiagents/memory/learn/stores.py:27-59 (`LearnEntry`) */ export declare class LearnEntry { id: string; content: string; metadata: Record; createdAt: string; updatedAt: string; useCount: number; lastUsed: string | null; constructor(init: LearnEntryInit); /** stores.py:38-47 - snake_case keys so files interoperate with Python. */ toDict(): LearnEntryData; /** stores.py:49-59 */ static fromDict(data: Record): LearnEntry; } /** * Key/value backend used by `BaseStore` instead of the JSON file. * Python parity: `StorageBackendProtocol` (storage/protocols.py) as consumed by * `BaseJSONStore` (storage/base.py:155-160, :173-176, :195-199). */ export interface LearnStorageBackend { load(key: string): Record | null; save(key: string, data: Record): void; delete(key: string): boolean; exists(key: string): boolean; listKeys?(prefix?: string): string[]; } /** * SQLite key/value backend. * Python parity: praisonaiagents/storage/backends.py:160-300 (`SQLiteBackend`) * * Same schema as Python (`key TEXT PRIMARY KEY, data TEXT, created_at, * updated_at`) so a database written by either SDK is readable by the other. * Requires the optional `better-sqlite3` package; throws * {@link LearnBackendNotAvailableError} at construction when it is missing. */ export declare class SQLiteLearnBackend implements LearnStorageBackend { readonly dbPath: string; readonly tableName: string; private _db; /** * @param dbPath Path to the SQLite database file (backends.py:177). * Defaults to `/learn/learn.db` when omitted. * @param tableName Storage table name (backends.py:178, default `praison_storage`). * @param autoCreate Create the table if it does not exist (backends.py:179). */ constructor(dbPath?: string | null, tableName?: string, autoCreate?: boolean); /** backends.py:219-238 */ private _createTable; /** backends.py:240-255 */ save(key: string, data: Record): void; /** backends.py:257-271 */ load(key: string): Record | null; /** backends.py:273-284 */ delete(key: string): boolean; exists(key: string): boolean; /** backends.py:286-300 */ listKeys(prefix?: string): string[]; /** Close the underlying connection (no Python counterpart; connections are per-thread there). */ close(): void; } /** * Redis backend placeholder. * Python parity: `RedisBackend` is not part of `praisonaiagents`; it is lazily * imported from the `praisonai` package and raises `ImportError` otherwise * (storage/backends.py:337-380). `LearnManager` requests it with * `RedisBackend(url=..., prefix="praison:learn:")` (manager.py:197-204). * * Not yet ported to TypeScript: the constructor always throws * {@link LearnBackendNotAvailableError}. */ export declare class RedisLearnBackend implements LearnStorageBackend { readonly url: string; readonly prefix: string; constructor(url?: string, prefix?: string); load(_key: string): Record | null; save(_key: string, _data: Record): void; delete(_key: string): boolean; exists(_key: string): boolean; } /** * MongoDB backend placeholder. * Python parity: `MongoDBBackend` is lazily imported from the `praisonai` * package (storage/backends.py:337-380); `LearnManager` requests it with * `MongoDBBackend(url=..., collection="praison_learn")` (manager.py:206-213). * * Not yet ported to TypeScript: the constructor always throws * {@link LearnBackendNotAvailableError}. */ export declare class MongoDBLearnBackend implements LearnStorageBackend { readonly url: string; readonly collection: string; constructor(url?: string, collection?: string); load(_key: string): Record | null; save(_key: string, _data: Record): void; delete(_key: string): boolean; exists(_key: string): boolean; } /** * Constructor options for {@link BaseStore}. * Python parity: praisonaiagents/memory/learn/stores.py:70-78 (`BaseStore.__init__`) */ export interface BaseStoreOptions { /** Explicit file path; defaults to `///.json` (stores.py:121-126). */ storePath?: string | null; /** Owner id; `"default"` when omitted (stores.py:79). */ userId?: string | null; /** `"private"` (default) or `"shared"` - only selects the directory segment (stores.py:74, :124). */ scope?: string; /** Pluggable key/value backend; `null` means JSON file (stores.py:75). */ backend?: LearnStorageBackend | null; /** Per-store cap, 0 = unbounded (stores.py:76). */ maxEntries?: number; /** Archive entries unused for this many days, 0 = never (stores.py:77). */ retentionDays?: number; } /** * Abstract base class for learning stores. * Python parity: praisonaiagents/memory/learn/stores.py:62-343 (`BaseStore`) */ export declare abstract class BaseStore implements LearnProtocol { readonly userId: string; readonly scope: string; readonly maxEntries: number; readonly retentionDays: number; readonly storePath: string; protected _backend: LearnStorageBackend | null; protected _entries: Map; protected _wasUpdated: boolean; private _store; constructor(options?: BaseStoreOptions); /** Name of the store, used for file naming (stores.py:106-110). */ abstract get storeName(): string; /** Whether this store has been modified since the last reset (stores.py:112-115). */ get wasUpdated(): boolean; /** stores.py:117-119 */ resetUpdated(): void; /** Number of active entries (Python reads `store._entries` directly, manager.py:324-329). */ get entryCount(): number; /** stores.py:121-126 - `///.json`, directory ensured. */ protected _defaultPath(): string; /** stores.py:128-133 */ protected _load(): void; /** stores.py:135-137 */ protected _save(): void; /** * Add a new entry with deduplication (stores.py:139-175). An exact * (trimmed, case-insensitive) content match returns the existing entry * instead of creating a duplicate; supplied metadata is merged into it. */ add(content: string, metadata?: Record | null): LearnEntry; /** Record usage telemetry for retrieved entries (stores.py:177-190). */ protected _touch(entries: LearnEntry[]): void; /** stores.py:192-194 */ get(entryId: string): LearnEntry | null; /** Simple substring search, case-insensitive (stores.py:196-205). */ search(query: string, limit?: number): LearnEntry[]; /** All entries, most recently updated first (stores.py:207-213). */ listAll(limit?: number): LearnEntry[]; /** stores.py:215-226 */ update(entryId: string, content: string, metadata?: Record | null): LearnEntry | null; /** stores.py:228-235 */ delete(entryId: string): boolean; /** stores.py:237-243 */ clear(): number; /** Recoverable archive sidecar, `.archive.json` (stores.py:245-247). */ protected _archivePath(): string; /** * Append evicted entries to the archive; returns `true` only when durably * written (stores.py:249-275). */ protected _archive(entries: LearnEntry[]): boolean; /** Whether an entry exceeds the retention window (stores.py:277-287). */ protected _isStale(entry: LearnEntry, now: Date): boolean; /** * Archive stale and least-used/oldest excess entries (stores.py:289-343). * Returns the number archived; 0 (no-op) when neither limit is configured. * * @param save Persist the active store after pruning. * @param protectId Entry id that must never be evicted. */ prune(save?: boolean, protectId?: string | null): number; } /** User preferences and profile (stores.py:346-359). */ export declare class PersonaStore extends BaseStore { get storeName(): string; /** stores.py:353-355 */ addPreference(preference: string, category?: string): LearnEntry; /** stores.py:357-359 */ addProfile(profileData: string, aspect?: string): LearnEntry; } /** Observations and learnings (stores.py:362-375). */ export declare class InsightStore extends BaseStore { get storeName(): string; /** stores.py:369-371 */ addInsight(insight: string, source?: string): LearnEntry; /** stores.py:373-375 */ addObservation(observation: string, context?: string): LearnEntry; } /** Session/conversation context (stores.py:378-391). */ export declare class ThreadStore extends BaseStore { get storeName(): string; /** stores.py:385-387 */ addThreadSummary(summary: string, threadId: string): LearnEntry; /** stores.py:389-391 */ addContext(context: string, threadId: string): LearnEntry; } /** Reusable knowledge patterns (stores.py:394-403). */ export declare class PatternStore extends BaseStore { get storeName(): string; /** stores.py:401-403 */ addPattern(pattern: string, patternType?: string): LearnEntry; } /** Decision logging (stores.py:406-424). */ export declare class DecisionStore extends BaseStore { get storeName(): string; /** stores.py:413-424 */ addDecision(decision: string, reasoning?: string, outcome?: string): LearnEntry; } /** Outcome signals and feedback (stores.py:427-444). */ export declare class FeedbackStore extends BaseStore { get storeName(): string; /** stores.py:434-444 */ addFeedback(feedback: string, rating?: number | null, source?: string): LearnEntry; } /** Self-improvement proposals (stores.py:447-465). */ export declare class ImprovementStore extends BaseStore { get storeName(): string; /** stores.py:454-465 */ addImprovement(proposal: string, area?: string, priority?: string): LearnEntry; }