Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
export const TAKEOVER_ENTRY_TYPE: "ov-takeover";
export const OVERVIEW_MARKER: "[OpenViking Session Context]";
export interface TakeoverMessage {
role: string;
content?: unknown;
timestamp?: number;
[key: string]: any;
}
/**
* A commit that archived but whose Working Memory was not ready in time. While
* one is set, no second takeover commit runs — later turns re-check this same
* archive by its uri. Persisted so it survives `pi -c` / `pi -p`.
*/
export interface PendingArchive {
archiveUri: string;
taskId: string;
historyUri: string;
/** The entry the frozen covered prefix ends at; "" for a native-compaction archive. */
coveredThroughEntryId: string;
coveredUserTurns: number;
frozenTokens: number;
nativeCompaction?: boolean;
}
export interface TakeoverPersistedState {
/** The pi entry id the covered prefix ends at (inclusive); "" when none. */
coveredThroughEntryId?: string;
/** Display count; also the whole boundary of a 0.4.1-or-earlier state. */
coveredUserTurns: number;
overview: string;
/** 0.4.1 and earlier only: fingerprint of the last covered context message. */
fingerprint?: string | null;
pendingTokens: number;
lastSeenUserTurns?: number;
syncedEntryCount?: number;
/** A committed archive still waiting on its Working Memory, or null. */
pendingArchive?: PendingArchive | null;
/** A permanent delivery gap: the archive is missing messages. Blocks advance. */
captureGap?: boolean;
archiveUri?: string;
historyUri?: string;
}
export interface TakeoverConfig {
takeoverEnabled?: boolean;
takeoverTokenThreshold?: number;
takeoverKeepRecentTurns?: number;
takeoverOverviewBudget?: number;
takeoverOverviewPollMs?: number;
takeoverOverviewPollMax?: number;
}
export interface SyncBranchResult {
added: number;
tokens: number;
allDelivered: boolean;
queued?: number;
permanentFailures?: number;
}
export interface TakeoverIo {
/** Deliver a pi branch to the server before committing. */
syncBranch?: (branch: any[]) => Promise<SyncBranchResult> | SyncBranchResult;
/** Drain this session's queue within `budgetMs`; true once nothing of it is undelivered. */
flush?: (budgetMs?: number) => Promise<boolean> | boolean;
commit?: (opts?: { queueOnFailure?: boolean; keepRecentCount?: number; timeoutMs?: number; enableWorkingMemory?: boolean }) => Promise<unknown> | unknown;
/** Read one archive's `.overview.md` by its uri; null until it is ready. */
readArchiveOverview?: (archiveUri: string, timeoutMs?: number) => Promise<string | null> | string | null;
/** An archive's terminal state from its `.done` / `.failed.json` markers; null when unknown. */
archiveState?: (archiveUri: string, timeoutMs?: number) => Promise<"completed" | "failed" | "pending" | null> | string | null;
/** Exact server keep_recent_count for a retained tail (message count). */
captureCount?: (branchSlice: any[]) => number;
persistEntry?: (customType: string, data: TakeoverPersistedState) => void;
getWatermark?: () => number;
/** Messages OpenViking will never receive; a capture gap when > 0. */
droppedCount?: () => number;
availableTools?: () => string[];
sleep?: (ms: number) => Promise<void>;
/** Clock for handler deadlines; defaults to Date.now. */
now?: () => number;
/** Why the last commit request returned no result, e.g. `HTTP 500: ...`. */
lastCommitError?: () => string;
log?: (message: string) => void;
}
/** Budget for takeover work inside one pi event handler (hosts cap them at 30s). */
export const HANDLER_BUDGET_MS: number;
/** Absolute epoch-ms deadline for the handler a call runs in. */
export interface HandlerDeadline {
deadline?: number;
}
export interface CommitOutcome {
accepted: boolean;
reason: string;
archiveUri?: string;
taskId?: string;
}
export function flattenContent(msg: TakeoverMessage): string;
export function fingerprintMessage(msg: TakeoverMessage): string;
export function isUserTurnStart(msg: TakeoverMessage): boolean;
export function countUserTurns(messages: TakeoverMessage[]): number;
export function findBoundaryIndex(messages: TakeoverMessage[], coveredUserTurns: number): number;
/** pi's context projection of `getBranch()`: compaction-aware, context edits applied. */
export function projectContextEntries(branch: any[]): any[];
export function estimateTokens(text: string): number;
export function truncateToTokens(text: string, budget: number): string;
export function estimatePayloadTokens(payload: any): number;
export function buildOverviewMessage(overview: string, firstKeptTs?: number, budget?: number, recoveryHint?: string): TakeoverMessage;
export function countUndeliveredForSession(pendingEntries: any[], sid: string): number;
export function deriveHistoryUri(archiveUri: string): string;
export function commitOutcome(committed: unknown): CommitOutcome;
/** A user-facing reading of a `skipped` commit's `reason`. */
export function describeSkip(reason: string, keepRecentCount?: number): string;
export type TakeoverState = TakeoverPersistedState & {
coveredThroughEntryId: string;
lastSeenUserTurns: number;
syncedEntryCount: number;
committing: boolean;
pendingArchive: PendingArchive | null;
captureGap: boolean;
archiveUri: string;
historyUri: string;
};
export class TakeoverCore {
constructor(opts?: { config?: TakeoverConfig; io?: TakeoverIo });
get enabled(): boolean;
get state(): TakeoverState;
/** Why the last commitAndAdvance() returned false; empty after a success. */
lastFailure: string;
restore(entries: any[]): TakeoverState;
/** `branch` is pi's `getBranch()`; the boundary is located on its context projection. */
transformContext(messages: TakeoverMessage[], branch?: any[] | (() => any[])): TakeoverMessage[];
onTurnSynced(estTokens: number, branch?: any[] | (() => any[]), opts?: HandlerDeadline): Promise<boolean>;
/** One check of a pending archive, e.g. before a prompt; true when the boundary advanced. */
resumePending(branch?: any[] | (() => any[]), opts?: HandlerDeadline): Promise<boolean>;
commitAndAdvance(branch?: any[] | (() => any[]), opts?: HandlerDeadline): Promise<boolean>;
handleBeforeCompact(
preparation?: { firstKeptEntryId?: string; tokensBefore?: number; signal?: AbortSignal },
branch?: any[] | (() => any[]),
opts?: HandlerDeadline,
): Promise<
| {
compaction: {
summary: string;
firstKeptEntryId: string;
tokensBefore: number;
details: { source: string };
};
}
| undefined
>;
shutdown(): Promise<void>;
resetBoundary(reason?: string): void;
truncatedOverview(): string;
recoveryHint(archiveUri?: string, historyUri?: string): string;
recordCaptureGap(): void;
persistedState(): TakeoverPersistedState;
persist(): void;
readOverviewOnce(archiveUri: string, timeoutMs?: number): Promise<string>;
pollArchiveOverview(archiveUri: string, signal?: AbortSignal, until?: number): Promise<{ overview: string; terminal: boolean }>;
}