@nguyentamdat/mempalace 1.0.0 → 1.0.2

package/README.md

@@ -6,27 +6,66 @@ A structured, persistent memory system for AI agents — featuring a palace meta
 
 This is a **Bun/TypeScript** port of the original [mempalace](https://github.com/milla-jovovich/mempalace) by [milla-jovovich](https://github.com/milla-jovovich).
 
+> **OpenCode users**: See [opencode-mempalace](https://github.com/nguyentamdat/opencode-mempalace) for plug-and-play integration.
+
 ## Requirements
 
 - [Bun](https://bun.sh/) ≥ 1.0
-- [ChromaDB](https://www.trychroma.com/) server running (`chroma run`)
+- [ChromaDB](https://www.trychroma.com/) server running
 
 ## Install
 
 ```bash
+npm install @nguyentamdat/mempalace
+# or
 git clone https://github.com/nguyentamdat/mempalace-js.git
 cd mempalace-js
 bun install
 ```
 
+## Setup
+
+### 1. Start ChromaDB
+
+```bash
+# Docker (recommended)
+docker run -d --name chromadb -p 127.0.0.1:8001:8000 \
+  -v chromadb-data:/chroma/chroma --restart unless-stopped \
+  chromadb/chroma:latest
+
+# Or pip
+pip install chromadb
+chroma run --port 8001
+```
+
+### 2. Configure
+
+The default ChromaDB URL is `http://localhost:8000`. Override via environment variable or config:
+
+```bash
+# Environment variable
+export CHROMA_URL=http://localhost:8001
+
+# Or in ~/.mempalace/config.json
+{
+  "chroma_url": "http://localhost:8001",
+  "palace_path": "~/.mempalace/palace",
+  "collection_name": "mempalace_drawers",
+  "topic_wings": ["work", "personal", "technical", "creative"]
+}
+```
+
+### 3. Initialize
+
+```bash
+bun run src/index.ts init /path/to/project
+```
+
 ## Usage
 
 ### CLI
 
 ```bash
-# Initialize a new palace
-bun run src/index.ts init
-
 # Mine project files into the palace
 bun run src/index.ts mine --mode projects --path ./my-project
 
@@ -36,7 +75,7 @@ bun run src/index.ts mine --mode convos --path ./transcripts
 # Search memories
 bun run src/index.ts search "some query"
 
-# Compress memories with AAAK dialect
+# Compress memories with AAAK dialect (~30x reduction)
 bun run src/index.ts compress
 
 # Load memory layers (wake-up)
@@ -54,23 +93,29 @@ bun run src/index.ts status
 Run as a JSON-RPC MCP server over stdin/stdout (19 tools):
 
 ```bash
-bun run src/mcp-server.ts
+CHROMA_URL=http://localhost:8001 bun run src/mcp-server.ts
 ```
 
-Tools include: `mempalace_search`, `mempalace_kg_query`, `mempalace_kg_timeline`, `mempalace_kg_add`, `mempalace_kg_invalidate`, `mempalace_diary_write`, `mempalace_diary_read`, `mempalace_status`, `mempalace_list_wings`, `mempalace_list_rooms`, `mempalace_add_drawer`, `mempalace_delete_drawer`, `mempalace_traverse`, `mempalace_find_tunnels`, and more.
+Tools: `mempalace_search`, `mempalace_kg_query`, `mempalace_kg_timeline`, `mempalace_kg_add`, `mempalace_kg_invalidate`, `mempalace_diary_write`, `mempalace_diary_read`, `mempalace_status`, `mempalace_list_wings`, `mempalace_list_rooms`, `mempalace_get_taxonomy`, `mempalace_add_drawer`, `mempalace_delete_drawer`, `mempalace_check_duplicate`, `mempalace_traverse`, `mempalace_find_tunnels`, `mempalace_graph_stats`, `mempalace_get_aaak_spec`.
 
 ## Architecture
 
 ### Palace Structure
 
 ```
-Palace (~/.mempalace/)
-├── Wings (top-level categories: work, personal, health, etc.)
+~/.mempalace/
+├── palace/           (ChromaDB collection data reference)
+├── config.json       (palace configuration)
+├── entity_registry.json
+├── identity.txt      (Layer 0 — who am I)
+└── knowledge_graph.db (SQLite)
+
+Palace (in ChromaDB)
+├── Wings (top-level categories: work, personal, technical, etc.)
 │   └── Rooms (specific topics within a wing)
-│       └── Drawers (individual memories stored in ChromaDB)
-├── Knowledge Graph (SQLite — entities + temporal triples)
-├── Diary (daily entries)
-└── Config (config.json, entity_registry.json, identity.txt)
+│       └── Drawers (individual memories with metadata)
+├── Diary wing (per-agent daily entries)
+└── Embeddings (DefaultEmbeddingFunction)
 ```
 
 ### Memory Layers
@@ -84,7 +129,7 @@ Palace (~/.mempalace/)
 
 ### AAAK Compression Dialect
 
-A compact encoding format for memories that reduces token usage while preserving meaning. Includes emotion codes, flag signals, and stop-word removal.
+A compact encoding format for memories that reduces token usage ~30x while preserving meaning. Uses 3-letter entity codes, emotion markers, pipe-separated fields, and importance stars (★–★★★★★).
 
 ### Knowledge Graph
 
@@ -94,7 +139,8 @@ SQLite-based temporal entity-relationship graph with validity windows and confid
 
 | Module | Description |
 |--------|-------------|
-| `config.ts` | Palace configuration management |
+| `config.ts` | Palace configuration (env vars, config.json, defaults) |
+| `mcp-server.ts` | JSON-RPC MCP server (19 tools) |
 | `knowledge-graph.ts` | Temporal entity-relationship graph (bun:sqlite) |
 | `dialect.ts` | AAAK compression dialect |
 | `layers.ts` | 4-layer memory stack |
@@ -110,7 +156,6 @@ SQLite-based temporal entity-relationship graph with validity windows and confid
 | `room-detector-local.ts` | Room detection from folder structure |
 | `spellcheck.ts` | Optional spell correction |
 | `split-mega-files.ts` | Split concatenated transcripts |
-| `mcp-server.ts` | JSON-RPC MCP server (19 tools) |
 
 ## Tests
 
@@ -118,6 +163,11 @@ SQLite-based temporal entity-relationship graph with validity windows and confid
 bun test
 ```
 
+## Related
+
+- [opencode-mempalace](https://github.com/nguyentamdat/opencode-mempalace) — OpenCode plugin for automatic integration
+- [mempalace](https://github.com/milla-jovovich/mempalace) — Original Python implementation
+
 ## Acknowledgements
 
 This project is a Bun/TypeScript port of the original [mempalace](https://github.com/milla-jovovich/mempalace) by [milla-jovovich](https://github.com/milla-jovovich). All credit for the palace architecture, AAAK compression dialect, knowledge graph design, memory layer system, and MCP tool definitions goes to their work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nguyentamdat/mempalace",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Give your AI a memory. No API key required.",
   "type": "module",
   "bin": {
@@ -13,10 +13,11 @@
     "mcp": "bun run src/mcp-server.ts"
   },
   "dependencies": {
+    "@clack/prompts": "^0.9.1",
     "chromadb": "^1.9.2",
+    "chromadb-default-embed": "^2.14.0",
     "citty": "^0.1.6",
-    "js-yaml": "^4.1.0",
-    "@clack/prompts": "^0.9.1"
+    "js-yaml": "^4.1.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/commands/compress.ts

@@ -1,5 +1,6 @@
 import { defineCommand } from "citty";
 import { resolvePalacePath } from "../cli";
+import { MempalaceConfig } from "../config";
 
 export default defineCommand({
   meta: { description: "Compress drawers using AAAK Dialect (~30x reduction)" },
@@ -40,7 +41,7 @@ export default defineCommand({
     let client: InstanceType<typeof ChromaClient>;
     let col: Awaited<ReturnType<InstanceType<typeof ChromaClient>["getCollection"]>>;
     try {
-      client = new ChromaClient({ path: palacePath });
+      client = new ChromaClient({ path: new MempalaceConfig().chromaUrl });
       col = await client.getCollection({
         name: "mempalace_drawers",
         embeddingFunction: new DefaultEmbeddingFunction(),

package/src/config.ts

@@ -10,6 +10,7 @@ import { homedir } from "os";
 
 export const DEFAULT_PALACE_PATH = join(homedir(), ".mempalace", "palace");
 export const DEFAULT_COLLECTION_NAME = "mempalace_drawers";
+export const DEFAULT_CHROMA_URL = process.env.CHROMA_URL ?? "http://localhost:8000";
 
 export const DEFAULT_TOPIC_WINGS = [
   "emotions",
@@ -89,6 +90,12 @@ export class MempalaceConfig {
     return (this.fileConfig.hall_keywords as Record<string, string[]>) ?? DEFAULT_HALL_KEYWORDS;
   }
 
+  get chromaUrl(): string {
+    const envVal = process.env.CHROMA_URL;
+    if (envVal) return envVal;
+    return (this.fileConfig.chroma_url as string) ?? DEFAULT_CHROMA_URL;
+  }
+
   init(): string {
     mkdirSync(this.configDir, { recursive: true });
     if (!existsSync(this.configFile)) {

package/src/convo-miner.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { mkdirSync, readdirSync, statSync } from "node:fs";
 import { basename, extname, resolve } from "node:path";
 import { ChromaClient } from "chromadb";
+import { MempalaceConfig } from "./config";
 
 import { extractMemories } from "./general-extractor";
 import { normalize } from "./normalize";
@@ -163,7 +164,7 @@ export function detectConvoRoom(content: string): string {
 
 export async function getCollection(palacePath: string): Promise<DrawerCollection> {
   mkdirSync(palacePath, { recursive: true });
-  const client = new ChromaClient();
+  const client = new ChromaClient({ path: new MempalaceConfig().chromaUrl });
   return client.getOrCreateCollection({ name: COLLECTION_NAME });
 }
 

package/src/layers.ts

@@ -146,8 +146,8 @@ async function loadDialect(): Promise<DialectLike> {
   return dialectPromise;
 }
 
-async function getCollection(palacePath: string, collectionName: string): Promise<Collection> {
-  const client = new ChromaClient({ path: palacePath });
+async function getCollection(collectionName: string): Promise<Collection> {
+  const client = new ChromaClient({ path: new MempalaceConfig().chromaUrl });
   return await client.getCollection({ name: collectionName } as never);
 }
 
@@ -198,7 +198,7 @@ export class Layer1 {
     let collection: Collection;
 
     try {
-      collection = await getCollection(this.palacePath, this.collectionName);
+      collection = await getCollection(this.collectionName);
     } catch {
       return "## L1 — No palace found. Run: mempalace mine <dir>";
     }
@@ -294,7 +294,7 @@ export class Layer2 {
     let collection: Collection;
 
     try {
-      collection = await getCollection(this.palacePath, this.collectionName);
+      collection = await getCollection(this.collectionName);
     } catch {
       return "No palace found.";
     }
@@ -354,7 +354,7 @@ export class Layer3 {
     let collection: Collection;
 
     try {
-      collection = await getCollection(this.palacePath, this.collectionName);
+      collection = await getCollection(this.collectionName);
     } catch {
       return "No palace found.";
     }
@@ -402,7 +402,7 @@ export class Layer3 {
     let collection: Collection;
 
     try {
-      collection = await getCollection(this.palacePath, this.collectionName);
+      collection = await getCollection(this.collectionName);
     } catch {
       return [];
     }
@@ -499,7 +499,7 @@ export class MemoryStack {
     };
 
     try {
-      const collection = await getCollection(this.palacePath, new MempalaceConfig().collectionName);
+      const collection = await getCollection(new MempalaceConfig().collectionName);
       result.totalDrawers = await collection.count();
     } catch {
       result.totalDrawers = 0;

package/src/mcp-server.ts

@@ -176,7 +176,7 @@ function toDirection(value: unknown): KgDirection {
 
 async function getCollection(create = false): Promise<DrawerCollection | null> {
   try {
-    const client = new ChromaClient();
+    const client = new ChromaClient({ path: config.chromaUrl });
     if (create) {
       return await client.getOrCreateCollection({
         name: config.collectionName,

package/src/miner.ts

@@ -9,6 +9,7 @@ import {
 import { basename, extname, relative, resolve } from "node:path";
 import { ChromaClient, DefaultEmbeddingFunction, IncludeEnum } from "chromadb";
 import yaml from "js-yaml";
+import { MempalaceConfig } from "./config";
 
 export const READABLE_EXTENSIONS = new Set([
 	".txt",
@@ -291,7 +292,7 @@ export async function getCollection(
 	palacePath: string,
 ): Promise<DrawerCollection> {
 	mkdirSync(palacePath, { recursive: true });
-	const client = new ChromaClient();
+	const client = new ChromaClient({ path: new MempalaceConfig().chromaUrl });
 	return client.getOrCreateCollection({ name: COLLECTION_NAME });
 }
 
@@ -562,7 +563,7 @@ export async function mine(
 export async function status(palacePath: string): Promise<void> {
 	try {
 		mkdirSync(palacePath, { recursive: true });
-    const client = new ChromaClient();
+    const client = new ChromaClient({ path: new MempalaceConfig().chromaUrl });
     const collection = await client.getCollection({
       name: COLLECTION_NAME,
       embeddingFunction: new DefaultEmbeddingFunction(),

package/src/palace-graph.ts

@@ -37,7 +37,7 @@ export async function getCollection(
   config: MempalaceConfig = new MempalaceConfig(),
 ): Promise<ChromaCollection | null> {
   try {
-    const client = new ChromaClient({ path: config.palacePath });
+    const client = new ChromaClient({ path: config.chromaUrl });
     return (await client.getCollection({
       name: config.collectionName,
       embeddingFunction: undefined as any,

package/src/searcher.ts

@@ -38,7 +38,7 @@ function buildWhereFilter(wing?: string, room?: string) {
 async function getDrawerCollection(palacePath: string) {
   const config = new MempalaceConfig();
   const collectionName = config.collectionName;
-  const client = new ChromaClient({ path: palacePath || config.palacePath });
+  const client = new ChromaClient({ path: config.chromaUrl });
   const embeddingFunction = new DefaultEmbeddingFunction();
 
   try {
@@ -69,8 +69,8 @@ export async function search({
 
   try {
     const kwargs = {
-      query_texts: [query],
-      n_results: nResults,
+      queryTexts: [query],
+      nResults: nResults,
       include: ["documents", "metadatas", "distances"],
     } as unknown as DrawerQueryParams;
 
@@ -141,8 +141,8 @@ export async function searchMemories({
 
   try {
     const kwargs = {
-      query_texts: [query],
-      n_results: nResults,
+      queryTexts: [query],
+      nResults: nResults,
       include: ["documents", "metadatas", "distances"],
     } as unknown as DrawerQueryParams;