ahok-skill 1.3.1

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "singleQuote": false,
+  "trailingComma": "all",
+  "tabWidth": 4,
+  "endOfLine": "auto",
+  "semi": true,
+  "bracketSpacing": true
+}

package/Dockerfile

@@ -0,0 +1,59 @@
+# ===== BUILD STAGE =====
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Install system dependencies required for native module compilation,
+# plus curl and bash (needed to run the Bun installation script)
+RUN apk add --no-cache python3 make g++ curl bash
+
+# Copy package manifests to install dependencies
+COPY package*.json ./
+
+# Install all dependencies (including devDependencies) using NPM
+RUN npm install
+
+# Copy source code and build the application
+COPY src/ ./src/
+COPY tsconfig.json ./
+RUN npm run build
+
+# Remove devDependencies to reduce image size 
+# (Removing all the devDependencies that we dont need in the final build)
+RUN npm prune --omit=dev
+
+
+# ===== PRODUCTION STAGE =====
+FROM node:20-alpine AS production
+
+WORKDIR /app
+
+# Install timezone data for proper TZ support
+RUN apk add --no-cache tzdata
+
+# Create a dedicated non-root user for security
+RUN addgroup -g 1001 -S appgroup \
+  && adduser -u 1001 -S appuser -G appgroup
+
+# Copy only production artifacts from the builder stage
+COPY --from=builder /app/node_modules ./node_modules/
+COPY --from=builder /app/dist ./dist/
+COPY package.json ./
+
+# Create a directory for persistent data and secure file permissions
+RUN mkdir -p /data \
+  && chown -R appuser:appgroup /data /app \
+  && chmod -R go-w /app
+
+# Switch to non-root user
+USER appuser
+
+# Expose the application port
+EXPOSE 8080
+
+# Define a lightweight health check that verifies the /health endpoint
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:8080/health', (res) => process.exit(res.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"
+
+# Start the application using npm
+ENTRYPOINT ["npm", "start"]

package/RAW_SKILL.md

@@ -0,0 +1,219 @@
+---
+name: ahok-memory
+description: "Long-term memory storage and retrieval for AI agents. Use when: remembering user preferences, storing context, recalling past conversations, personalizing responses, building agent memory."
+source: ahok-memory-cloud
+api_base: https://zqmt62peqz.us-east-1.awsapprunner.com
+---
+
+# Ahok Memory Cloud
+
+Universal long-term memory for AI agents. Store and retrieve memories across conversations.
+
+## Claude Desktop Integration (MCP)
+
+Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "ahok-memory": {
+      "command": "npx",
+      "args": ["-y", "openmemory-js", "mcp"],
+      "env": {
+        "OM_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Or connect to the hosted MCP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "ahok-memory": {
+      "url": "https://zqmt62peqz.us-east-1.awsapprunner.com/mcp",
+      "headers": {
+        "x-api-key": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+Once connected, Claude will have access to:
+
+- **openmemory_query** - Search memories semantically
+- **openmemory_store** - Save new memories
+- **openmemory_list** - List recent memories
+- **openmemory_get** - Fetch a specific memory
+- **openmemory_reinforce** - Boost memory importance
+
+## Quick Start
+
+### Authentication
+All requests require an API key in the `x-api-key` header.
+Get your key from: https://your-dashboard-url/dashboard
+
+### Store a Memory
+
+```bash
+curl -X POST https://zqmt62peqz.us-east-1.awsapprunner.com/memory/add \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -d '{"content": "User prefers dark mode", "user_id": "user123"}'
+```
+
+### Recall Memories
+
+```bash
+curl -X POST https://zqmt62peqz.us-east-1.awsapprunner.com/query \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -d '{"query": "What are the user preferences?", "k": 5}'
+```
+
+## API Endpoints
+
+### POST /memory/add
+Store a new memory.
+
+**Request Body:**
+```json
+{
+  "content": "The information to remember",
+  "user_id": "optional-user-identifier",
+  "tags": ["optional", "tags"],
+  "metadata": {"any": "json object"},
+  "memory_key_id": "optional-workspace-uuid"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "uuid",
+  "primary_sector": "semantic|procedural|episodic",
+  "sectors": ["semantic"],
+  "chunks": 1
+}
+```
+
+### POST /query
+Search memories semantically.
+
+**Request Body:**
+```json
+{
+  "query": "natural language search",
+  "k": 5,
+  "user_id": "optional-filter"
+}
+```
+
+**Response:**
+```json
+{
+  "query": "natural language search",
+  "result": "Formatted memory results as text",
+  "matches": [
+    {"id": "uuid", "content": "...", "score": 0.95}
+  ]
+}
+```
+
+### POST /memories
+Simplified endpoint for storing memories (alias for /memory/add).
+
+### GET /memory/all
+List all memories with pagination.
+
+**Query Parameters:**
+- `user_id`: Filter by user
+- `l`: Limit (default 50)
+- `u`: Offset (default 0)
+- `key_id`: Filter by workspace
+
+### DELETE /memory/{id}
+Delete a specific memory.
+
+## Memory Sectors
+
+Memories are automatically classified into sectors:
+- **semantic**: Facts, knowledge, preferences
+- **procedural**: How-to, processes, workflows  
+- **episodic**: Events, conversations, experiences
+
+## Best Practices
+
+1. **Always include user_id** for multi-user applications
+2. **Use tags** for easier filtering and organization
+3. **Query at conversation start** to personalize responses
+4. **Store important facts** as they're shared by users
+5. **Use workspaces** to isolate memories by project/context
+
+## Integration Examples
+
+### Python
+```python
+import requests
+
+API_KEY = "your-api-key"
+BASE_URL = "https://zqmt62peqz.us-east-1.awsapprunner.com"
+
+def remember(content, user_id=None):
+    return requests.post(f"{BASE_URL}/memory/add", 
+        headers={"x-api-key": API_KEY},
+        json={"content": content, "user_id": user_id}
+    ).json()
+
+def recall(query, k=5):
+    return requests.post(f"{BASE_URL}/query",
+        headers={"x-api-key": API_KEY},
+        json={"query": query, "k": k}
+    ).json()
+```
+
+### JavaScript/TypeScript
+```typescript
+const API_KEY = "your-api-key";
+const BASE_URL = "https://zqmt62peqz.us-east-1.awsapprunner.com";
+
+async function remember(content: string, userId?: string) {
+  const res = await fetch(`${BASE_URL}/memory/add`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
+    body: JSON.stringify({ content, user_id: userId })
+  });
+  return res.json();
+}
+
+async function recall(query: string, k = 5) {
+  const res = await fetch(`${BASE_URL}/query`, {
+    method: "POST", 
+    headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
+    body: JSON.stringify({ query, k })
+  });
+  return res.json();
+}
+```
+
+## Claude/Anthropic Integration
+
+When using with Claude, add this to your system prompt:
+
+```
+You have access to long-term memory via the Ahok Memory API.
+
+To remember something important:
+POST /memory/add with {"content": "what to remember"}
+
+To recall relevant context:
+POST /query with {"query": "what to search for"}
+
+Always check memory at the start of conversations for personalization.
+Store important user preferences and facts as they're shared.
+```

package/README.md

@@ -0,0 +1,277 @@
+# openmemory javascript sdk
+
+> **real long-term memory for ai agents. not rag. not a vector db. self-hosted.**
+
+[![npm version](https://img.shields.io/npm/v/openmemory-js.svg)](https://www.npmjs.com/package/openmemory-js)
+[![license](https://img.shields.io/github/license/CaviraOSS/OpenMemory)](https://github.com/CaviraOSS/OpenMemory/blob/main/LICENSE)
+[![discord](https://img.shields.io/discord/1300368230320697404?label=Discord)](https://discord.gg/P7HaRayqTh)
+
+openmemory is a **cognitive memory engine** for llms and agents.
+
+- 🧠 real long-term memory (not just embeddings in a table)
+- 💾 self-hosted, local-first (sqlite / postgres)
+- 🧩 integrations: mcp, claude desktop, cursor, windsurf
+- 📥 sources: github, notion, google drive, onedrive, web crawler
+- 🔍 explainable traces (see *why* something was recalled)
+
+your model stays stateless. **your app stops being amnesiac.**
+
+---
+
+## quick start
+
+```bash
+npm install openmemory-js
+```
+
+```typescript
+import { Memory } from "openmemory-js"
+
+const mem = new Memory()
+await mem.add("user likes spicy food", { user_id: "u1" })
+const results = await mem.search("food?", { user_id: "u1" })
+```
+
+drop this into:
+
+- node backends
+- clis
+- local tools
+- anything that needs durable memory without running a separate service
+
+**that's it.** you're now running a fully local cognitive memory engine 🎉
+
+---
+
+## 📥 sources (connectors)
+
+ingest data from external sources directly into memory:
+
+```typescript
+const github = await mem.source("github")
+await github.connect({ token: "ghp_..." })
+await github.ingest_all({ repo: "owner/repo" })
+```
+
+available sources: `github`, `notion`, `google_drive`, `google_sheets`, `google_slides`, `onedrive`, `web_crawler`
+
+---
+
+## features
+
+✅ **local-first** - runs entirely on your machine, zero external dependencies  
+✅ **multi-sector memory** - episodic, semantic, procedural, emotional, reflective  
+✅ **temporal knowledge graph** - time-aware facts with validity periods  
+✅ **memory decay** - adaptive forgetting with sector-specific rates  
+✅ **waypoint graph** - associative recall paths for better retrieval  
+✅ **explainable traces** - see exactly why memories were recalled  
+✅ **zero config** - works out of the box with sensible defaults  
+
+---
+
+## cognitive sectors
+
+openmemory automatically classifies content into 5 cognitive sectors:
+
+| sector | description | examples | decay rate |
+|--------|-------------|----------|------------|
+| **episodic** | time-bound events & experiences | "yesterday i attended a conference" | medium |
+| **semantic** | timeless facts & knowledge | "paris is the capital of france" | very low |
+| **procedural** | skills, procedures, how-tos | "to deploy: build, test, push" | low |
+| **emotional** | feelings, sentiment, mood | "i'm excited about this project!" | high |
+| **reflective** | meta-cognition, insights | "i learn best through practice" | very low |
+
+---
+
+## configuration
+
+### environment variables
+
+```bash
+# database
+OM_DB_PATH=./data/om.db              # sqlite file path (default: ./data/openmemory.sqlite)
+OM_DB_URL=sqlite://:memory:          # or use in-memory db
+
+# embeddings
+OM_EMBEDDINGS=ollama                 # synthetic | openai | gemini | ollama
+OM_OLLAMA_URL=http://localhost:11434
+OM_OLLAMA_MODEL=embeddinggemma       # or nomic-embed-text, mxbai-embed-large
+
+# openai
+OPENAI_API_KEY=sk-...
+OM_OPENAI_MODEL=text-embedding-3-small
+
+# gemini
+GEMINI_API_KEY=AIza...
+
+# performance tier
+OM_TIER=deep                         # fast | smart | deep | hybrid
+OM_VEC_DIM=768                       # vector dimension (must match model)
+
+# metadata backend (optional)
+OM_METADATA_BACKEND=postgres         # sqlite (default) | postgres
+OM_PG_HOST=localhost
+OM_PG_PORT=5432
+OM_PG_DB=openmemory
+OM_PG_USER=postgres
+OM_PG_PASSWORD=...
+
+# vector backend (optional)
+OM_VECTOR_BACKEND=valkey             # default uses metadata backend
+OM_VALKEY_URL=redis://localhost:6379
+```
+
+### programmatic usage
+
+```typescript
+import { Memory } from 'openmemory-js';
+
+const mem = new Memory('user-123');  // optional user_id
+
+// add memories
+await mem.add(
+    "user prefers dark mode",
+    {
+        tags: ["preference", "ui"],
+        created_at: Date.now()
+    }
+);
+
+// search
+const results = await mem.search("user settings", {
+    user_id: "user-123",
+    limit: 10,
+    sectors: ["semantic", "procedural"]
+});
+
+// get by id
+const memory = await mem.get("uuid-here");
+
+// wipe all data (useful for testing)
+await mem.wipe();
+```
+
+---
+
+## performance tiers
+
+- `fast` - synthetic embeddings (no api calls), instant
+- `smart` - hybrid semantic + synthetic for balanced speed/accuracy
+- `deep` - pure semantic embeddings for maximum accuracy
+- `hybrid` - adaptive based on query complexity
+
+---
+
+## mcp server
+
+openmemory-js includes an mcp server for integration with claude desktop, cursor, windsurf, and other mcp clients:
+
+```bash
+npx openmemory-js serve --port 3000
+```
+
+### claude desktop / cursor / windsurf
+
+```json
+{
+  "mcpServers": {
+    "openmemory": {
+      "command": "npx",
+      "args": ["openmemory-js", "serve"]
+    }
+  }
+}
+```
+
+available mcp tools:
+
+- `openmemory_query` - search memories
+- `openmemory_store` - add new memories
+- `openmemory_list` - list all memories
+- `openmemory_get` - get memory by id
+- `openmemory_reinforce` - reinforce a memory
+
+---
+
+## examples
+
+```typescript
+// multi-user support
+const mem = new Memory();
+await mem.add("alice likes python", { user_id: "alice" });
+await mem.add("bob likes rust", { user_id: "bob" });
+
+const alicePrefs = await mem.search("what does alice like?", { user_id: "alice" });
+// returns python results only
+
+// temporal filtering
+const recent = await mem.search("user activity", {
+    startTime: Date.now() - 86400000,  // last 24 hours
+    endTime: Date.now()
+});
+
+// sector-specific queries
+const facts = await mem.search("company info", { sectors: ["semantic"] });
+const howtos = await mem.search("deployment", { sectors: ["procedural"] });
+```
+
+---
+
+## api reference
+
+### `new Memory(user_id?: string)`
+
+create a new memory instance with optional default user_id.
+
+### `async add(content: string, metadata?: object): Promise<hsg_mem>`
+
+store a new memory.
+
+**parameters:**
+- `content` - text content to store
+- `metadata` - optional metadata object:
+  - `user_id` - user identifier
+  - `tags` - array of tag strings
+  - `created_at` - timestamp
+  - any other custom fields
+
+**returns:** memory object with `id`, `primary_sector`, `sectors`
+
+### `async search(query: string, options?: object): Promise<hsg_q_result[]>`
+
+search for relevant memories.
+
+**parameters:**
+- `query` - search text
+- `options`:
+  - `user_id` - filter by user
+  - `limit` - max results (default: 10)
+  - `sectors` - array of sectors to search
+  - `startTime` - filter memories after this timestamp
+  - `endTime` - filter memories before this timestamp
+
+**returns:** array of memory results with `id`, `content`, `score`, `sectors`, `salience`, `tags`, `meta`
+
+### `async get(id: string): Promise<memory | null>`
+
+retrieve a memory by id.
+
+### `async wipe(): Promise<void>`
+
+**⚠️ danger**: delete all memories, vectors, and waypoints. useful for testing.
+
+---
+
+## license
+
+apache 2.0
+
+---
+
+## links
+
+- [main repository](https://github.com/CaviraOSS/OpenMemory)
+- [python sdk](https://pypi.org/project/openmemory-py/)
+- [vs code extension](https://marketplace.visualstudio.com/items?itemName=Nullure.openmemory-vscode)
+- [documentation](https://openmemory.cavira.app/docs/sdks/javascript)
+- [discord](https://discord.gg/P7HaRayqTh)

package/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ahok-memory
+description: "Universal long-term memory system for AI agents. Use when: remembering user preferences, storing persistent context, recalling past conversations, personalizing responses, or creating new agent memories that persist across sessions."
+---
+
+# Ahok Memory Cloud
+
+Universal long-term memory for AI agents. Store and retrieve memories across conversations.
+
+## Quick Start
+
+1.  **Get API Key**: Obtain from dashboard.
+2.  **Add Memory**: `POST /memory/add` with `content`.
+3.  **Recall Memory**: `POST /query` with `query`.
+
+See [references/api_reference.md](references/api_reference.md) for full API documentation.
+See [references/examples.md](references/examples.md) for code integration examples.
+
+## Best Practices
+
+1.  **Always include user_id** for multi-user applications to ensure proper data isolation.
+2.  **Use tags** for easier filtering and organization.
+3.  **Query at conversation start** to personalize responses based on past interactions.
+4.  **Store important facts** as they are shared by users (e.g., preferences, project details).
+5.  **Use workspaces** to isolate memories by project or context.
+
+## Claude Desktop Integration (MCP)
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ahok-memory": {
+      "command": "npx",
+      "args": ["-y", "ahok-skill", "mcp"],
+      "env": {
+        "OM_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Or connect via hosted MCP:
+
+```json
+{
+  "mcpServers": {
+    "ahok-memory": {
+      "url": "https://zqmt62peqz.us-east-1.awsapprunner.com/mcp",
+      "headers": {
+        "x-api-key": "your-api-key-here"
+      }
+    }
+  }
+}
+```