@dungle-scrubs/hippo 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+import type { Message } from "@mariozechner/pi-ai";
+import type { Database } from "better-sqlite3";
+/**
+ * LLM completion interface — structurally compatible with marrow's LlmClient.
+ *
+ * Accepts pi-ai's Message[] so marrow's OpenRouterLlmClient can be passed
+ * directly without an adapter.
+ */
+export interface LlmClient {
+    /**
+     * Send messages with a system prompt and get a text response.
+     *
+     * @param messages - pi-ai Message array (UserMessage | AssistantMessage | ToolResultMessage)
+     * @param systemPrompt - System-level instruction
+     * @param signal - Optional abort signal
+     * @returns The model's text response
+     */
+    complete(messages: Message[], systemPrompt: string, signal?: AbortSignal): Promise<string>;
+}
+/** Embedding function injected by the consumer. */
+export type EmbedFn = (text: string, signal?: AbortSignal) => Promise<Float32Array>;
+/** Chunk kind discriminator. */
+export type ChunkKind = "fact" | "memory";
+/** A row from the chunks table. */
+export interface Chunk {
+    readonly access_count: number;
+    readonly agent_id: string;
+    readonly content: string;
+    readonly content_hash: string | null;
+    readonly created_at: string;
+    readonly embedding: Buffer;
+    readonly id: string;
+    readonly kind: ChunkKind;
+    readonly last_accessed_at: string;
+    readonly metadata: string | null;
+    readonly encounter_count: number;
+    readonly running_intensity: number;
+    readonly superseded_by: string | null;
+}
+/** A row from the memory_blocks table. */
+export interface MemoryBlock {
+    readonly agent_id: string;
+    readonly key: string;
+    readonly updated_at: string;
+    readonly value: string;
+}
+/** A single extracted fact from the LLM extraction pipeline. */
+export interface ExtractedFact {
+    readonly fact: string;
+    readonly intensity: number;
+}
+/** Classification result for conflict resolution. */
+export type ConflictClassification = "DISTINCT" | "DUPLICATE" | "SUPERSEDES";
+/** Result of a search query against chunks. */
+export interface SearchResult {
+    readonly chunk: Chunk;
+    readonly score: number;
+}
+/** Options for creating hippo tools. */
+export interface HippoOptions {
+    readonly agentId: string;
+    readonly db: Database;
+    readonly embed: EmbedFn;
+    readonly llm: LlmClient;
+    readonly messagesTable?: string;
+}
+/** Result summary returned by remember_facts. */
+export interface RememberFactsResult {
+    readonly facts: readonly RememberFactAction[];
+}
+/** Action taken for a single extracted fact. */
+export type RememberFactAction = {
+    readonly action: "inserted";
+    readonly content: string;
+    readonly intensity: number;
+} | {
+    readonly action: "reinforced";
+    readonly content: string;
+    readonly newIntensity: number;
+    readonly oldIntensity: number;
+} | {
+    readonly action: "superseded";
+    readonly content: string;
+    readonly oldContent: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/ulid.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Minimal ULID generator (Crockford Base32, 48-bit timestamp + 80-bit random).
+ *
+ * No external dependency needed — ULIDs are just encoded timestamps with randomness.
+ */
+/**
+ * Generate a ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * @param timestamp - Optional timestamp in ms (defaults to Date.now())
+ * @returns 26-character ULID string
+ */
+export declare function ulid(timestamp?: number): string;
+//# sourceMappingURL=ulid.d.ts.map

package/dist/ulid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ulid.d.ts","sourceRoot":"","sources":["../src/ulid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAY/C"}

package/dist/ulid.js

@@ -0,0 +1,39 @@
+/**
+ * Minimal ULID generator (Crockford Base32, 48-bit timestamp + 80-bit random).
+ *
+ * No external dependency needed — ULIDs are just encoded timestamps with randomness.
+ */
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * Encode a number into Crockford Base32 of exactly `len` characters.
+ *
+ * @param value - Non-negative integer to encode
+ * @param len - Output string length (zero-padded)
+ * @returns Crockford Base32 string
+ */
+function encodeBase32(value, len) {
+    let result = "";
+    for (let i = len - 1; i >= 0; i--) {
+        result = ENCODING[value & 0x1f] + result;
+        value = Math.floor(value / 32);
+    }
+    return result;
+}
+/**
+ * Generate a ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * @param timestamp - Optional timestamp in ms (defaults to Date.now())
+ * @returns 26-character ULID string
+ */
+export function ulid(timestamp) {
+    const ts = timestamp ?? Date.now();
+    const timePart = encodeBase32(ts, 10);
+    // 16 random chars × 5 bits = 80 bits of randomness
+    const randomBytes = crypto.getRandomValues(new Uint8Array(16));
+    let randomPart = "";
+    for (const byte of randomBytes) {
+        randomPart += ENCODING[byte & 0x1f];
+    }
+    return timePart + randomPart;
+}
+//# sourceMappingURL=ulid.js.map

package/dist/ulid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ulid.js","sourceRoot":"","sources":["../src/ulid.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AAEpD;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,KAAa,EAAE,GAAW;IAC/C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,GAAG,QAAQ,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;QACzC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,IAAI,CAAC,SAAkB;IACtC,MAAM,EAAE,GAAG,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAG,YAAY,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAEtC,mDAAmD;IACnD,MAAM,WAAW,GAAG,MAAM,CAAC,eAAe,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/D,IAAI,UAAU,GAAG,EAAE,CAAC;IACpB,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAChC,UAAU,IAAI,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,QAAQ,GAAG,UAAU,CAAC;AAC9B,CAAC"}

package/package.json

@@ -0,0 +1,70 @@
+{
+	"name": "@dungle-scrubs/hippo",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "Persistent memory for AI agents — facts, semantic search, conflict resolution, and decay. SQLite-backed, zero external services.",
+	"license": "MIT",
+	"author": "Kevin Frilot",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dungle-scrubs/hippo.git"
+	},
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"types": "./dist/index.d.ts",
+	"bin": {
+		"hippo": "./dist/cli.js",
+		"hippo-server": "./dist/server/index.js"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"check": "biome check .",
+		"format": "biome format --write .",
+		"lint": "biome lint .",
+		"lint:fix": "biome lint --fix .",
+		"prepare": "husky",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.27.0",
+		"@sinclair/typebox": "^0.34.48",
+		"commander": "^14.0.3",
+		"express": "^5.2.1",
+		"zod": "^4.3.6"
+	},
+	"peerDependencies": {
+		"@mariozechner/pi-agent-core": ">=0.52.0",
+		"@mariozechner/pi-ai": ">=0.52.0",
+		"better-sqlite3": ">=12.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.14",
+		"@mariozechner/pi-agent-core": "0.52.12",
+		"@mariozechner/pi-ai": "0.52.12",
+		"@types/better-sqlite3": "^7.6.13",
+		"@types/express": "^5.0.6",
+		"better-sqlite3": "^12.6.2",
+		"husky": "^9.1.7",
+		"typescript": "^5.9.3",
+		"vitest": "^4.0.18"
+	},
+	"engines": {
+		"node": ">=22"
+	},
+	"packageManager": "pnpm@10.28.1",
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"better-sqlite3",
+			"esbuild"
+		]
+	}
+}