@o-lang/agent-memory 1.0.3 → 1.0.5

package/capability.js

@@ -0,0 +1,209 @@
+// capability.js
+require('dotenv').config();
+const Database = require('better-sqlite3');
+const crypto = require('node:crypto');
+
+const dbPath = process.env.SQLITE_PATH || './agent_memory.db';
+const db = new Database(dbPath);
+
+// ── TABLE SETUP ─────────────────────────────────────────
+db.exec(`
+CREATE TABLE IF NOT EXISTS chat_turns (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  role       TEXT NOT NULL,
+  content    TEXT NOT NULL,
+  token_hash TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_chat_session
+  ON chat_turns (session_id, created_at);
+
+CREATE TABLE IF NOT EXISTS facts (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  role       TEXT NOT NULL,
+  content    TEXT NOT NULL,
+  token_hash TEXT NOT NULL,
+  score      REAL NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_facts_session
+  ON facts (session_id, score DESC, created_at ASC);
+`);
+
+// ── HELPER: HASH CONTENT ───────────────────────────────
+function genTokenHash(sessionId, role, content) {
+  return crypto.createHash('sha256')
+    .update(`${sessionId}:${role}:${content}:${Date.now()}`)
+    .digest('hex')
+    .slice(0, 16);
+}
+
+// ── CHAT MEMORY FUNCTIONS ─────────────────────────────
+function memoryWrite(sessionId, role, content) {
+  if (!sessionId) throw new Error("memory_write requires 'session_id'");
+  if (!['user', 'assistant', 'system'].includes(role)) throw new Error(`Invalid role '${role}'`);
+  if (!content) throw new Error("memory_write requires 'content'");
+
+  const tokenHash = genTokenHash(sessionId, role, content);
+  const res = db.prepare(`
+    INSERT INTO chat_turns (session_id, role, content, token_hash, created_at)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(sessionId, role, content, tokenHash, Date.now());
+
+  return { turn_index: res.lastInsertRowid, session_id: sessionId, role, token_hash: tokenHash };
+}
+
+function memoryRead(sessionId, lastN = 10) {
+  if (!sessionId) throw new Error("memory_read requires 'session_id'");
+
+  const rows = db.prepare(`
+    SELECT role, content, created_at FROM (
+      SELECT role, content, created_at
+      FROM chat_turns
+      WHERE session_id = ?
+      ORDER BY created_at DESC
+      LIMIT ?
+    ) ORDER BY created_at ASC
+  `).all(sessionId, lastN);
+
+  const text = rows.map(r => `${r.role === 'user' ? 'User' : r.role === 'assistant' ? 'Assistant' : 'System'}: ${r.content}`).join('\n');
+  return { text, turns: rows, empty: rows.length === 0 };
+}
+
+// ── FACT MEMORY FUNCTIONS ─────────────────────────────
+function memoryFactWrite(sessionId, role, content, score = 1.0) {
+  if (!sessionId || !content) throw new Error("memory_fact_write requires sessionId and content");
+  const tokenHash = crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+  const existing = db.prepare(`SELECT 1 FROM facts WHERE session_id=? AND token_hash=?`).get(sessionId, tokenHash);
+  if (existing) return null; // deduplicate
+
+  const res = db.prepare(`
+    INSERT INTO facts (session_id, role, content, token_hash, score, created_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `).run(sessionId, role, content, tokenHash, score, Date.now());
+
+  return { fact_id: res.lastInsertRowid, session_id: sessionId, role, token_hash: tokenHash, score };
+}
+
+function memoryFactWriteBatch(sessionId, facts = []) {
+  if (!Array.isArray(facts)) throw new Error("facts must be an array");
+  const results = [];
+  const insert = db.prepare(`
+    INSERT INTO facts (session_id, role, content, token_hash, score, created_at)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `);
+
+  const existingHashes = db.prepare(`SELECT token_hash FROM facts WHERE session_id=?`).all(sessionId).map(r => r.token_hash);
+  for (const f of facts) {
+    const tokenHash = crypto.createHash('sha256').update(f.content).digest('hex').slice(0, 16);
+    if (!existingHashes.includes(tokenHash)) {
+      const res = insert.run(sessionId, f.role || 'system', f.content, tokenHash, f.score || 1.0, Date.now());
+      results.push({ fact_id: res.lastInsertRowid, session_id: sessionId, token_hash: tokenHash, score: f.score || 1.0 });
+    }
+  }
+  return results;
+}
+
+function memoryFactRead(sessionId, limit = 20) {
+  const rows = db.prepare(`
+    SELECT role, content, token_hash, score
+    FROM facts
+    WHERE session_id = ?
+    ORDER BY score DESC, created_at ASC
+    LIMIT ?
+  `).all(sessionId, limit);
+
+  const text = rows.map(r => `${r.role === 'user' ? 'User' : r.role === 'assistant' ? 'Assistant' : 'System'}: ${r.content}`).join('\n');
+  return { text, facts: rows, empty: rows.length === 0 };
+}
+
+// ── SELF-MAINTAIN MEMORY ─────────────────────────────
+async function selfMaintainMemory(sessionId, llmResolver, opts = {}) {
+  const { threshold = 20, factScore = 0.8, lastNTurns = 20 } = opts;
+
+  const recent = memoryRead(sessionId, lastNTurns);
+  if (recent.turns.length < threshold) return null;
+
+  // Auto summarization using LLM resolver
+  let summary = '';
+  if (llmResolver) {
+    const prompt = `Summarize the following conversation into concise facts:\n${recent.text}`;
+    const llmResponse = await llmResolver(prompt);
+    summary = llmResponse?.text || recent.turns.map(t => t.content).join(' | ');
+  } else {
+    summary = recent.turns.map(t => t.content).join(' | ');
+  }
+
+  return memoryFactWrite(sessionId, 'system', summary, factScore);
+}
+
+// ── SEMANTIC QUERY / RETRIEVAL ───────────────────────
+function memoryQuery(sessionId, query, limit = 5) {
+  // Simple token matching across facts
+  const rows = db.prepare(`
+    SELECT role, content, token_hash, score
+    FROM facts
+    WHERE session_id = ? AND content LIKE ?
+    ORDER BY score DESC, created_at ASC
+    LIMIT ?
+  `).all(sessionId, `%${query}%`, limit);
+
+  return rows;
+}
+
+// ── CONTEXT INJECTION ───────────────────────────────
+function memoryContext(sessionId, maxTurns = 10, maxFacts = 5) {
+  const recent = memoryRead(sessionId, maxTurns);
+  const topFacts = memoryFactRead(sessionId, maxFacts);
+
+  const context = [
+    topFacts.text ? `### Agent Facts:\n${topFacts.text}` : '',
+    recent.text ? `### Recent Chat:\n${recent.text}` : ''
+  ].filter(Boolean).join('\n\n');
+
+  return context;
+}
+
+// ── COUNT & PRUNE ────────────────────────────────────
+function memoryCount(sessionId) {
+  const chatCount = db.prepare(`SELECT COUNT(*) AS count FROM chat_turns WHERE session_id=?`).get(sessionId).count;
+  const factCount = db.prepare(`SELECT COUNT(*) AS count FROM facts WHERE session_id=?`).get(sessionId).count;
+  return { chatCount, factCount };
+}
+
+function memoryPrune(sessionId, keepLastTurns = 20, minFactScore = 0.1) {
+  const deletedTurns = db.prepare(`
+    DELETE FROM chat_turns
+    WHERE id NOT IN (
+      SELECT id FROM chat_turns
+      WHERE session_id=?
+      ORDER BY created_at DESC
+      LIMIT ?
+    )
+  `).run(sessionId, keepLastTurns).changes;
+
+  const deletedFacts = db.prepare(`
+    DELETE FROM facts
+    WHERE session_id=? AND score < ?
+  `).run(sessionId, minFactScore).changes;
+
+  return { deletedTurns, deletedFacts };
+}
+
+// ── EXPORTS ─────────────────────────────────────────
+module.exports = {
+  memoryWrite,
+  memoryRead,
+  memoryFactWrite,
+  memoryFactWriteBatch,
+  memoryFactRead,
+  selfMaintainMemory,
+  memoryQuery,
+  memoryContext,
+  memoryCount,
+  memoryPrune
+};

package/capability.test.js

@@ -0,0 +1,122 @@
+// capability.test.js
+// Tests for @o-lang/agent-memory (v2)
+
+let memoryWrite, memoryRead, memoryFactWrite, memoryFactWriteBatch, memoryFactRead;
+
+beforeEach(() => {
+  jest.resetModules();
+  process.env.SQLITE_PATH = ':memory:';
+
+  const cap = require('./capability');
+
+  memoryWrite            = cap.memoryWrite;
+  memoryRead             = cap.memoryRead;
+  memoryFactWrite        = cap.memoryFactWrite;
+  memoryFactWriteBatch   = cap.memoryFactWriteBatch;
+  memoryFactRead         = cap.memoryFactRead;
+});
+
+// ── CHAT MEMORY ─────────────────────────────────────
+
+describe('memoryWrite / memoryRead', () => {
+
+  test('Writes and reads chat history', () => {
+    const sid = 'chat-test';
+
+    memoryWrite(sid, 'user', 'Hello');
+    memoryWrite(sid, 'assistant', 'Hi there');
+
+    const result = memoryRead(sid, 10);
+
+    expect(result.empty).toBe(false);
+    expect(result.turns.length).toBe(2);
+    expect(result.text).toContain('Hello');
+  });
+
+  test('Respects lastN limit', () => {
+    const sid = 'limit-test';
+
+    for (let i = 0; i < 5; i++) {
+      memoryWrite(sid, 'user', `Msg ${i}`);
+    }
+
+    const result = memoryRead(sid, 2);
+
+    expect(result.turns.length).toBe(2);
+    expect(result.turns[1].content).toBe('Msg 4');
+  });
+
+  test('Sessions are isolated', () => {
+    memoryWrite('a', 'user', 'A');
+    memoryWrite('b', 'user', 'B');
+
+    const a = memoryRead('a');
+    const b = memoryRead('b');
+
+    expect(a.text.includes('B')).toBe(false);
+    expect(b.text.includes('A')).toBe(false);
+  });
+
+});
+
+// ── FACT MEMORY ─────────────────────────────────────
+
+describe('memoryFactWrite / memoryFactRead', () => {
+
+  test('Writes and reads facts', () => {
+    const sid = 'fact-test';
+
+    memoryFactWrite(sid, 'system', 'User likes short answers', 0.9);
+
+    const result = memoryFactRead(sid, 10);
+
+    expect(result.empty).toBe(false);
+    expect(result.facts.length).toBe(1);
+  });
+
+  test('Deduplicates identical facts', () => {
+    const sid = 'dedup-test';
+
+    memoryFactWrite(sid, 'system', 'Same fact', 0.9);
+    memoryFactWrite(sid, 'system', 'Same fact', 0.8);
+
+    const result = memoryFactRead(sid);
+
+    expect(result.facts.length).toBe(1);
+  });
+
+});
+
+// ── BATCH FACT WRITE ────────────────────────────────
+
+describe('memoryFactWriteBatch', () => {
+
+  test('Writes multiple facts', () => {
+    const sid = 'batch-test';
+
+    const res = memoryFactWriteBatch(sid, [
+      { content: 'Fact 1', score: 0.9 },
+      { content: 'Fact 2', score: 0.8 }
+    ]);
+
+    expect(res.written).toBe(2);
+
+    const result = memoryFactRead(sid);
+
+    expect(result.facts.length).toBe(2);
+  });
+
+  test('Skips duplicates in batch', () => {
+    const sid = 'batch-dedup';
+
+    memoryFactWrite(sid, 'system', 'Fact 1', 0.9);
+
+    const res = memoryFactWriteBatch(sid, [
+      { content: 'Fact 1', score: 0.9 },
+      { content: 'Fact 2', score: 0.8 }
+    ]);
+
+    expect(res.written).toBe(1);
+  });
+
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o-lang/agent-memory",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Unified agent memory resolver for O-Lang. Combines short-term chat memory and long-term facts with deduplication and scoring.",
   "main": "index.js",
   "scripts": {
@@ -29,7 +29,7 @@
     "arm64"
   ],
   "files": [
-    "index.js",
+    "*.js",
     "README.md",
     "LICENSE"
   ],

package/resolver.js

@@ -0,0 +1,38 @@
+module.exports = {
+  resolverName: "agent-memory",
+  version:      "2.0.0",
+  specVersion:  "O-Lang/1.1",
+
+  inputs: [
+    {
+      name: "action",
+      type: "string",
+      required: true,
+      description: "Action string (memory_write, memory_read, memory_fact_write_batch, etc.)"
+    }
+  ],
+
+  outputs: [
+    { name: "text", type: "string" },
+    { name: "turns", type: "array" },
+    { name: "facts", type: "array" },
+    { name: "turn_index", type: "number" }
+  ],
+
+  exampleAction: 'memory_read "session-001"',
+
+  failures: [
+    { code: "MISSING_SESSION_ID", retries: 0 },
+    { code: "INVALID_ROLE",       retries: 0 },
+    { code: "MISSING_CONTENT",    retries: 0 },
+    { code: "INVALID_JSON",       retries: 0 },
+    { code: "LLM_PARSE_FAILED",   retries: 0 },
+    { code: "DB_ERROR",           retries: 1 }
+  ],
+
+  properties: {
+    handlesTemplatedPrompts: false,
+    deterministic: false,
+    sideEffects: true
+  }
+};

package/test-local-resolver.js

@@ -0,0 +1,24 @@
+// test-local-resolver.js
+const resolver = require('./index');
+
+async function test() {
+  console.log('=== WRITE ===');
+  console.log('User Turn:', resolver('Action memory_write "s1" "user" "Hello agent!"'));
+  console.log('Assistant Turn:', resolver('Action memory_write "s1" "assistant" "Hello, how can I help?"'));
+  console.log('System Fact:', resolver('Action memory_fact_write "s1" "system" "Always answer concisely" "0.9"'));
+
+  console.log('\n=== READ ===');
+  console.log(await resolver('Action memory_read "s1" "10"'));
+  console.log(await resolver('Action memory_fact_read "s1" "10"'));
+
+  console.log('\n=== SELF MAINTAIN ===');
+  console.log(await resolver('Action self_maintain "s1" "2" "0.8" "10"'));
+
+  console.log('\n=== COUNT ===');
+  console.log(resolver('Action count "s1"'));
+
+  console.log('\n=== PRUNE ===');
+  console.log(resolver('Action prune "s1" "1" "0.5"'));
+}
+
+test();