@tpsdev-ai/flair 0.2.1 → 0.3.1

package/README.md

@@ -3,11 +3,11 @@
 [![CI](https://github.com/tpsdev-ai/flair/actions/workflows/test.yml/badge.svg)](https://github.com/tpsdev-ai/flair/actions/workflows/test.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-**Identity, memory, and soul for AI agents.**
+**Identity, memory, and soul for AI agents. Runs standalone or as part of a [TPS](https://tps.dev) office.**
 
 Agents forget everything between sessions. Flair gives them a persistent sense of self — who they are, what they know, how they think — backed by cryptographic identity and semantic search.
 
-Built on [Harper](https://github.com/HarperFast/harper). Single process. No sidecars. Zero external API calls for embeddings.
+Built on [Harper](https://harper.fast). Single process. No sidecars. Zero external API calls for embeddings.
 
 ## Why
 
@@ -23,7 +23,7 @@ Flair fixes that:
 
 ## How It Works
 
-Flair is a native [Harper v5](https://github.com/HarperFast/harper) application. Harper handles HTTP, persistence (RocksDB), and application logic in a single process.
+Flair is a native [Harper v5](https://harper.fast) application. Harper handles HTTP, persistence (RocksDB), and application logic in a single process.
 
 ```
 Agent ──[Ed25519-signed request]──▶ Flair (Harper)
@@ -72,7 +72,7 @@ One Flair instance serves any number of agents. Each agent has its own keys, mem
 ## Quick Start
 
 ### Prerequisites
-- [Node.js 20+](https://nodejs.org/) (24+ recommended)
+- [Node.js 22+](https://nodejs.org/)
 
 ### Install & Run
 
@@ -92,53 +92,120 @@ flair status
 
 That's it. Your agent now has identity and memory.
 
-### Use with OpenClaw
+## Integration
+
+Flair works with any agent runtime. Pick the path that fits yours.
+
+### Standalone (Flair CLI)
+
+Use the `flair` CLI directly from any agent that can run shell commands.
+
+```bash
+# Write a memory
+flair memory add --agent mybot --content "learned something important"
+
+# Search by meaning
+flair memory search --agent mybot --q "that important thing"
+
+# Set personality
+flair soul set --agent mybot --key role --value "Security reviewer"
+
+# Cold-start bootstrap (soul + recent memories)
+flair bootstrap --agent mybot --max-tokens 4000
+
+# Backup / restore
+flair backup --admin-pass "$FLAIR_ADMIN_PASS"
+flair restore ./backup.json --admin-pass "$FLAIR_ADMIN_PASS"
+```
+
+### OpenClaw
+
+One command. Zero config.
 
 ```bash
-npm install @tpsdev-ai/openclaw-flair
+openclaw plugins install @tpsdev-ai/openclaw-flair
 ```
 
-Add to your `openclaw.json`:
-```json
-{
-  "memory": {
-    "provider": "@tpsdev-ai/openclaw-flair"
-  }
-}
+The plugin auto-detects your agent identity, provides `memory_store`/`memory_recall`/`memory_get` tools, and injects relevant memories at session start. See the [plugin README](plugins/openclaw-flair/README.md) for details.
+
+### Claude Code / Codex / Cursor
+
+Add a snippet to your `CLAUDE.md` (or `AGENTS.md`, `.codex/instructions.md`, etc.):
+
+```markdown
+## Memory
+
+You have persistent memory via Flair. Use it.
+
+### On session start
+Run: `flair bootstrap --agent mybot --max-tokens 4000`
+This returns your soul + recent memories. Read it — that's your context.
+
+### During work
+- Remember something: `flair memory add --agent mybot --content "what you learned"`
+- Search memory: `flair memory search --agent mybot --q "your query"`
+- Store a lesson: `flair memory add --agent mybot --content "lesson" --type lesson --durability persistent`
+
+### Rules
+- Bootstrap FIRST, before doing anything else
+- Store lessons and decisions immediately — don't wait
+- If you learn something that should survive restarts, write it to Flair
 ```
 
-Your agent will automatically remember things between sessions and recall them by meaning.
+### JavaScript / TypeScript (Client Library)
 
-### Use the CLI directly
+For custom integrations, use the lightweight client — no Harper, no embeddings, just HTTP + auth:
 
 ```bash
-# Write a memory
-flair memory add --agent mybot --content "Harper v5 sandbox blocks bare imports"
+npm install @tpsdev-ai/flair-client
+```
 
-# Search by meaning, not keywords
-flair memory search --agent mybot --q "native module loading issues"
+```typescript
+import { FlairClient } from '@tpsdev-ai/flair-client'
 
-# Set personality
-flair soul set --agent mybot --key role --value "Security reviewer, meticulous and skeptical"
+const flair = new FlairClient({
+  url: 'http://localhost:9926',  // or remote: https://flair.example.com
+  agentId: 'mybot',
+  // key auto-resolved from ~/.flair/keys/mybot.key
+})
 
-# Back up everything
-flair backup --admin-pass "$FLAIR_ADMIN_PASS"
+// Write a memory
+await flair.memory.write('Harper v5 sandbox blocks bare imports')
+
+// Search by meaning
+const results = await flair.memory.search('native module loading')
+
+// Cold-start bootstrap
+const ctx = await flair.bootstrap({ maxTokens: 4000 })
 
-# Restore from backup
-flair restore ./flair-backup-2026-03-15.json --admin-pass "$FLAIR_ADMIN_PASS"
+// Set personality
+await flair.soul.set('role', 'Security reviewer')
 ```
 
-### Cold Start Bootstrap
+See the [client README](packages/flair-client/README.md) for the full API.
 
-Agents can pull their full context on startup via the `BootstrapMemories` endpoint:
+### HTTP API (Any Language)
+
+Flair is a pure HTTP API. Use it from Python, Go, Rust, shell scripts — anything that can make HTTP requests and sign with Ed25519.
 
 ```bash
-curl -H "Authorization: TPS-Ed25519 ..." \
+# Search memories
+curl -H "Authorization: TPS-Ed25519 mybot:$TS:$NONCE:$SIG" \
+  -X POST http://localhost:9926/SemanticSearch \
+  -d '{"agentId": "mybot", "q": "deployment procedure", "limit": 5}'
+
+# Write a memory
+curl -H "Authorization: TPS-Ed25519 mybot:$TS:$NONCE:$SIG" \
+  -X PUT http://localhost:9926/Memory/mybot-123 \
+  -d '{"id": "mybot-123", "agentId": "mybot", "content": "...", "durability": "standard"}'
+
+# Bootstrap (soul + recent memories)
+curl -H "Authorization: TPS-Ed25519 mybot:$TS:$NONCE:$SIG" \
   -X POST http://localhost:9926/BootstrapMemories \
   -d '{"agentId": "mybot", "maxTokens": 4000}'
 ```
 
-Returns soul + recent memories + relevant context as a formatted block. Bounded context regardless of total memory size.
+Auth is Ed25519 — sign `agentId:timestamp:nonce:METHOD:/path` with your private key. See [SECURITY.md](SECURITY.md) for the full protocol.
 
 ## Architecture
 
@@ -154,11 +221,11 @@ flair/
 │   ├── embeddings-provider.ts # In-process nomic embeddings
 │   ├── Memory.ts             # Durability enforcement + auto-embed
 │   ├── Soul.ts               # Permanent-by-default personality
-│   ├── MemorySearch.ts       # Hybrid semantic + keyword search
+│   ├── SemanticSearch.ts     # Hybrid semantic + keyword search
 │   ├── MemoryBootstrap.ts    # Cold start context assembly
 │   └── MemoryFeed.ts         # Real-time memory changes
 ├── plugins/
-│   └── openclaw-memory/       # @tpsdev-ai/openclaw-flair plugin
+│   └── openclaw-flair/        # @tpsdev-ai/openclaw-flair plugin
 └── SECURITY.md                # Threat model + auth documentation
 ```
 
@@ -219,9 +286,9 @@ Integration tests spin up a real Harper instance on a random port, run the test
 
 ## Status
 
-> **Note:** Flair uses [Harper v5](https://github.com/HarperFast/harper), currently in beta. We run it in production daily and track upstream closely. Pin your Harper version.
+> **Note:** Flair uses [Harper v5](https://harper.fast), currently in beta. We run it in production daily and track upstream closely. Pin your Harper version.
 
-Flair is in active development and daily use. We dogfood it — the agents that build Flair use Flair for their own memory and identity. 7 agents, 150+ memories, running continuously since March 2026.
+Flair is in active development and daily use. We dogfood it — the agents that build Flair use Flair for their own memory and identity.
 
 **What works:**
 - ✅ Ed25519 agent identity and auth

package/dist/cli.js

@@ -42,7 +42,19 @@ function b64url(bytes) {
     return Buffer.from(bytes).toString("base64url");
 }
 async function api(method, path, body) {
-    const base = process.env.FLAIR_URL || "http://127.0.0.1:8787";
+    // Resolve port: FLAIR_URL env > ~/.flair/config.yaml > default 9926
+    let defaultUrl = "http://127.0.0.1:9926";
+    try {
+        const configPath = join(homedir(), ".flair", "config.yaml");
+        if (existsSync(configPath)) {
+            const yaml = readFileSync(configPath, "utf-8");
+            const portMatch = yaml.match(/port:\s*(\d+)/);
+            if (portMatch)
+                defaultUrl = `http://127.0.0.1:${portMatch[1]}`;
+        }
+    }
+    catch { /* ignore config read errors */ }
+    const base = process.env.FLAIR_URL || defaultUrl;
     const token = process.env.FLAIR_TOKEN;
     const res = await fetch(`${base}${path}`, {
         method,
@@ -57,16 +69,40 @@ async function api(method, path, body) {
         throw new Error(JSON.stringify(json));
     return json;
 }
+/** Find the agent's private key file from standard locations. */
+function resolveKeyPath(agentId) {
+    const candidates = [
+        process.env.FLAIR_KEY_DIR ? join(process.env.FLAIR_KEY_DIR, `${agentId}.key`) : null,
+        join(homedir(), ".flair", "keys", `${agentId}.key`),
+        join(homedir(), ".tps", "secrets", "flair", `${agentId}-priv.key`),
+    ].filter(Boolean);
+    return candidates.find((p) => existsSync(p)) ?? null;
+}
 /** Build a TPS-Ed25519 auth header from a raw 32-byte seed on disk. */
 function buildEd25519Auth(agentId, method, path, keyPath) {
-    const rawBuf = readFileSync(keyPath);
+    const raw = readFileSync(keyPath);
+    const pkcs8Header = Buffer.from("302e020100300506032b657004220420", "hex");
     let privKey;
-    if (rawBuf.length === 32) {
-        const pkcs8Header = Buffer.from("302e020100300506032b657004220420", "hex");
-        privKey = createPrivateKey({ key: Buffer.concat([pkcs8Header, rawBuf]), format: "der", type: "pkcs8" });
+    if (raw.length === 32) {
+        // Raw 32-byte seed
+        privKey = createPrivateKey({ key: Buffer.concat([pkcs8Header, raw]), format: "der", type: "pkcs8" });
     }
     else {
-        privKey = createPrivateKey(rawBuf);
+        // Try as base64-encoded PKCS8 DER (standard Flair key format)
+        const decoded = Buffer.from(raw.toString("utf-8").trim(), "base64");
+        if (decoded.length === 32) {
+            // Base64-encoded raw seed
+            privKey = createPrivateKey({ key: Buffer.concat([pkcs8Header, decoded]), format: "der", type: "pkcs8" });
+        }
+        else {
+            // Full PKCS8 DER or PEM
+            try {
+                privKey = createPrivateKey({ key: decoded, format: "der", type: "pkcs8" });
+            }
+            catch {
+                privKey = createPrivateKey(raw);
+            }
+        }
     }
     const ts = Date.now().toString();
     const nonce = randomUUID();
@@ -665,6 +701,91 @@ memory.command("list").requiredOption("--agent <id>").option("--tag <tag>")
     const q = new URLSearchParams({ agentId: opts.agent, ...(opts.tag ? { tag: opts.tag } : {}) }).toString();
     console.log(JSON.stringify(await api("GET", `/Memory?${q}`), null, 2));
 });
+// ─── flair search (top-level shortcut) ───────────────────────────────────────
+program
+    .command("search <query>")
+    .description("Search memories by meaning (shortcut for memory search)")
+    .requiredOption("--agent <id>", "Agent ID")
+    .option("--limit <n>", "Max results", "5")
+    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--key <path>", "Ed25519 private key path")
+    .action(async (query, opts) => {
+    try {
+        const baseUrl = opts.url || `http://127.0.0.1:${opts.port}`;
+        const headers = { "content-type": "application/json" };
+        const keyPath = opts.key || resolveKeyPath(opts.agent);
+        if (keyPath) {
+            headers["authorization"] = buildEd25519Auth(opts.agent, "POST", "/SemanticSearch", keyPath);
+        }
+        const res = await fetch(`${baseUrl}/SemanticSearch`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ agentId: opts.agent, q: query, limit: parseInt(opts.limit, 10) }),
+        });
+        if (!res.ok)
+            throw new Error(await res.text());
+        const result = await res.json();
+        const results = result.results || result || [];
+        if (!Array.isArray(results) || results.length === 0) {
+            console.log("No results found.");
+            return;
+        }
+        for (const r of results) {
+            const date = r.createdAt ? r.createdAt.slice(0, 10) : "";
+            const score = r._score ? `${(r._score * 100).toFixed(0)}%` : "";
+            const meta = [date, r.type, score].filter(Boolean).join(" · ");
+            console.log(`  ${r.content}`);
+            if (meta)
+                console.log(`  (${meta})`);
+            console.log();
+        }
+    }
+    catch (err) {
+        console.error(`Search failed: ${err.message}`);
+        process.exit(1);
+    }
+});
+// ─── flair bootstrap ─────────────────────────────────────────────────────────
+program
+    .command("bootstrap")
+    .description("Cold-start context: get soul + recent memories as formatted text")
+    .requiredOption("--agent <id>", "Agent ID")
+    .option("--max-tokens <n>", "Maximum tokens in output", "4000")
+    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--key <path>", "Ed25519 private key path")
+    .action(async (opts) => {
+    const baseUrl = opts.url || `http://127.0.0.1:${opts.port}`;
+    try {
+        const headers = { "content-type": "application/json" };
+        const keyPath = opts.key || resolveKeyPath(opts.agent);
+        if (keyPath) {
+            headers["authorization"] = buildEd25519Auth(opts.agent, "POST", "/BootstrapMemories", keyPath);
+        }
+        const res = await fetch(`${baseUrl}/BootstrapMemories`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ agentId: opts.agent, maxTokens: parseInt(opts.maxTokens, 10) }),
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`${res.status}: ${body}`);
+        }
+        const result = await res.json();
+        if (result.context) {
+            console.log(result.context);
+        }
+        else {
+            console.error("No context available.");
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`Bootstrap failed: ${err.message}`);
+        process.exit(1);
+    }
+});
 const soul = program.command("soul").description("Manage agent soul entries");
 soul.command("set").requiredOption("--agent <id>").requiredOption("--key <key>").requiredOption("--value <value>")
     .option("--durability <d>", "permanent")

package/dist/resources/MemoryBootstrap.js

@@ -54,12 +54,22 @@ export class BootstrapMemories extends Resource {
         let tokenBudget = maxTokens;
         let memoriesIncluded = 0;
         let memoriesAvailable = 0;
-        // --- 1. Soul records (unconditional — not subject to token budget) ---
-        // Soul is who you are. It's not optional context to be trimmed.
-        // Skill assignments (key='skill-assignment') are separated into their own section.
+        // --- 1. Soul records (budgeted — prioritized by key importance) ---
+        // Soul is who you are, but we still need to respect token budgets.
+        // Workspace files (SOUL.md, AGENTS.md) can be massive — they're already
+        // injected by the runtime via workspace context, so we prioritize
+        // concise soul entries over full file dumps.
+        const SOUL_KEY_PRIORITY = {
+            role: 0, identity: 1, thinking: 2, communication_style: 3,
+            team: 4, ownership: 5, infrastructure: 6, "user-context": 7,
+            // Full workspace files — lowest priority (runtime already injects these)
+            soul: 90, "workspace-rules": 91,
+        };
         const skillAssignments = [];
+        const soulMaxTokens = Math.floor(maxTokens * 0.4); // 40% of budget for soul
         if (includeSoul) {
             let soulTokens = 0;
+            const soulEntries = [];
             for await (const record of databases.flair.Soul.search()) {
                 if (record.agentId !== agentId)
                     continue;
@@ -68,11 +78,29 @@ export class BootstrapMemories extends Resource {
                     continue;
                 }
                 const line = `**${record.key}:** ${record.value}`;
-                sections.soul.push(line);
-                soulTokens += estimateTokens(line);
+                const tokens = estimateTokens(line);
+                const priority = SOUL_KEY_PRIORITY[record.key] ?? 50;
+                soulEntries.push({ key: record.key, line, tokens, priority });
+            }
+            // Sort by priority (lower = more important)
+            soulEntries.sort((a, b) => a.priority - b.priority);
+            for (const entry of soulEntries) {
+                if (soulTokens + entry.tokens > soulMaxTokens) {
+                    // Skip large entries that exceed budget — truncate or skip
+                    if (entry.priority >= 90)
+                        continue; // skip full workspace files
+                    // Truncate if it's important but too long
+                    const maxChars = (soulMaxTokens - soulTokens) * 4;
+                    if (maxChars > 100) {
+                        const truncated = `**${entry.key}:** ${entry.line.slice(entry.key.length + 6, entry.key.length + 6 + maxChars)}…(truncated)`;
+                        sections.soul.push(truncated);
+                        soulTokens += estimateTokens(truncated);
+                    }
+                    continue;
+                }
+                sections.soul.push(entry.line);
+                soulTokens += entry.tokens;
             }
-            // Soul tokens are tracked but don't reduce memory budget
-            tokenBudget = maxTokens; // memory budget is separate from soul
         }
         // --- 1b. Skill assignments (ordered by priority, conflict detection) ---
         if (skillAssignments.length > 0) {
@@ -134,15 +162,27 @@ export class BootstrapMemories extends Resource {
                 memoriesIncluded++;
             }
         }
-        // --- 3. Recent memories (last 24-48h, standard + persistent) ---
-        const sinceDate = since
-            ? new Date(since)
-            : new Date(Date.now() - 48 * 3600_000);
-        const recent = activeMemories
-            .filter((m) => m.durability !== "permanent" &&
-            m.createdAt &&
-            new Date(m.createdAt) >= sinceDate)
+        // --- 3. Recent memories (adaptive window) ---
+        // Start with 48h. If nothing found, widen to 7d, then 30d.
+        // This prevents empty recent sections for agents that were idle.
+        const nonPermanent = activeMemories
+            .filter((m) => m.durability !== "permanent" && m.createdAt)
             .sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+        let effectiveSince;
+        if (since) {
+            effectiveSince = new Date(since);
+        }
+        else {
+            const windows = [48 * 3600_000, 7 * 24 * 3600_000, 30 * 24 * 3600_000];
+            effectiveSince = new Date(Date.now() - windows[0]);
+            for (const w of windows) {
+                effectiveSince = new Date(Date.now() - w);
+                const count = nonPermanent.filter((m) => new Date(m.createdAt) >= effectiveSince).length;
+                if (count >= 3)
+                    break; // found enough recent memories
+            }
+        }
+        const recent = nonPermanent.filter((m) => new Date(m.createdAt) >= effectiveSince);
         // Budget: up to 40% of remaining for recent
         const recentBudget = Math.floor(tokenBudget * 0.4);
         let recentSpent = 0;

package/dist/resources/MemoryMaintenance.js

@@ -0,0 +1,90 @@
+/**
+ * MemoryMaintenance.ts — Maintenance worker for memory hygiene.
+ *
+ * POST /MemoryMaintenance/ — runs cleanup tasks:
+ *   1. Delete expired ephemeral memories (expiresAt < now)
+ *   2. Archive old session memories (> 30 days, standard durability)
+ *   3. Report stats
+ *
+ * Designed to run periodically (daily cron or heartbeat).
+ * Requires admin auth.
+ */
+export default class MemoryMaintenance {
+    static ROUTE = "MemoryMaintenance";
+    static METHOD = "POST";
+    async post(data) {
+        const { databases } = this;
+        const request = this.request;
+        const { dryRun = false, agentId } = data || {};
+        // Scope to authenticated agent. Admin can pass agentId for system-wide
+        // maintenance; non-admin always scoped to their own agent.
+        const authAgent = request?.headers?.get?.("x-tps-agent");
+        const isAdmin = request?.tpsAgentIsAdmin === true;
+        const targetAgent = isAdmin && agentId ? agentId : authAgent;
+        if (!targetAgent && !isAdmin) {
+            return { error: "agentId required" };
+        }
+        const now = new Date();
+        const stats = { expired: 0, archived: 0, total: 0, errors: 0, agent: targetAgent || "all" };
+        try {
+            for await (const record of databases.flair.Memory.search()) {
+                // Skip records not belonging to target agent (unless admin running system-wide)
+                if (targetAgent && record.agentId !== targetAgent)
+                    continue;
+                stats.total++;
+                // 1. Delete expired memories
+                if (record.expiresAt && new Date(record.expiresAt) < now) {
+                    if (!dryRun) {
+                        try {
+                            await databases.flair.Memory.delete(record.id);
+                            stats.expired++;
+                        }
+                        catch {
+                            stats.errors++;
+                        }
+                    }
+                    else {
+                        stats.expired++;
+                    }
+                    continue;
+                }
+                // 2. Archive old standard session memories (> 30 days)
+                // These are low-value session notes that weren't promoted to persistent.
+                // Archiving removes them from search results but keeps the data.
+                if (record.durability === "standard" &&
+                    record.type === "session" &&
+                    !record.archived &&
+                    record.createdAt) {
+                    const ageMs = now.getTime() - new Date(record.createdAt).getTime();
+                    const ageDays = ageMs / (24 * 3600_000);
+                    if (ageDays > 30) {
+                        if (!dryRun) {
+                            try {
+                                // Soft archive — set archived flag, keep data
+                                await databases.flair.Memory.update(record.id, {
+                                    ...record,
+                                    archived: true,
+                                    archivedAt: now.toISOString(),
+                                });
+                                stats.archived++;
+                            }
+                            catch {
+                                stats.errors++;
+                            }
+                        }
+                        else {
+                            stats.archived++;
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            return { error: err.message, stats };
+        }
+        return {
+            message: dryRun ? "Dry run complete" : "Maintenance complete",
+            stats,
+        };
+    }
+}

package/dist/resources/SemanticSearch.js

@@ -44,7 +44,7 @@ function compositeScore(semanticScore, record) {
 }
 export class SemanticSearch extends Resource {
     async post(data) {
-        const { agentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "composite" } = data || {};
+        const { agentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "composite", minScore = 0, since } = data || {};
         const subjectFilter = subjects
             ? new Set(subjects.map((s) => s.toLowerCase()))
             : subject
@@ -86,6 +86,39 @@ export class SemanticSearch extends Resource {
                 catch { }
             }
         }
+        // ─── Temporal intent detection ────────────────────────────────────────────
+        // If the query implies a time window and no explicit `since` was provided,
+        // auto-detect and apply a recency boost.
+        let sinceDate = since ? new Date(since) : null;
+        let temporalBoost = 1.0;
+        if (q && !sinceDate) {
+            const lq = String(q).toLowerCase();
+            if (/\btoday\b|\bthis morning\b|\bthis afternoon\b/.test(lq)) {
+                const d = new Date();
+                d.setHours(0, 0, 0, 0);
+                sinceDate = d;
+                temporalBoost = 1.5; // boost recent results for temporal queries
+            }
+            else if (/\byesterday\b/.test(lq)) {
+                const d = new Date();
+                d.setDate(d.getDate() - 1);
+                d.setHours(0, 0, 0, 0);
+                sinceDate = d;
+                temporalBoost = 1.3;
+            }
+            else if (/\bthis week\b|\blast few days\b/.test(lq)) {
+                sinceDate = new Date(Date.now() - 7 * 24 * 3600_000);
+                temporalBoost = 1.2;
+            }
+            else if (/\blast week\b/.test(lq)) {
+                sinceDate = new Date(Date.now() - 14 * 24 * 3600_000);
+                temporalBoost = 1.1;
+            }
+            else if (/\brecently\b|\blately\b/.test(lq)) {
+                sinceDate = new Date(Date.now() - 3 * 24 * 3600_000);
+                temporalBoost = 1.3;
+            }
+        }
         const results = [];
         // Iterate ALL memories, filter by agent ID set
         for await (const record of databases.flair.Memory.search()) {
@@ -95,24 +128,34 @@ export class SemanticSearch extends Resource {
                     continue;
             }
             if (record.archived === true)
-                continue; // soft-deleted — excluded from search by default
+                continue;
             if (record.expiresAt && Date.parse(record.expiresAt) < Date.now())
                 continue;
             if (tag && !(record.tags || []).includes(tag))
                 continue;
             if (subjectFilter && record.subject && !subjectFilter.has(String(record.subject).toLowerCase()))
                 continue;
-            let rawScore = 0;
+            // Time window filter
+            if (sinceDate && record.createdAt && new Date(record.createdAt) < sinceDate)
+                continue;
+            let semanticScore = 0;
+            let keywordHit = false;
             if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
-                rawScore += 0.5;
+                keywordHit = true;
             }
             if (qEmb && record.embedding && qEmb.length === record.embedding.length) {
-                rawScore += cosineSimilarity(qEmb, record.embedding);
+                semanticScore = cosineSimilarity(qEmb, record.embedding);
             }
+            // Keyword match is a small tiebreaker (5%), not a primary signal.
+            // This prevents weak semantic matches from ranking high just because
+            // a query word appears in the content.
+            const rawScore = semanticScore + (keywordHit ? 0.05 : 0);
             if (q && rawScore === 0)
                 continue;
-            // Apply composite scoring (temporal decay + durability + retrieval boost)
-            const finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+            // Apply composite scoring (temporal decay + durability + retrieval boost + temporal intent)
+            let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+            if (temporalBoost > 1.0)
+                finalScore *= temporalBoost;
             const { embedding, ...rest } = record;
             results.push({
                 ...rest,
@@ -131,6 +174,10 @@ export class SemanticSearch extends Resource {
             }
             filteredResults = results.filter((r) => !supersededIds.has(r.id));
         }
+        // Apply minimum score filter
+        if (minScore > 0) {
+            filteredResults = filteredResults.filter((r) => r._score >= minScore);
+        }
         filteredResults.sort((a, b) => b._score - a._score);
         const topResults = filteredResults.slice(0, limit);
         // Async hit tracking — don't block the response

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.2.1",
-  "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
+  "version": "0.3.1",
+  "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality \u2014 all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
   "repository": {
@@ -49,7 +49,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.0.0-beta.1",
+    "@harperfast/harper": "5.0.0-beta.4",
     "@node-llama-cpp/mac-arm64-metal": "^3.17.1",
     "commander": "14.0.3",
     "harper-fabric-embeddings": "^0.2.0",
@@ -62,5 +62,9 @@
   },
   "trustedDependencies": [
     "harper-fabric-embeddings"
+  ],
+  "workspaces": [
+    "packages/*",
+    "plugins/*"
   ]
-}
+}

package/resources/MemoryBootstrap.ts

@@ -68,12 +68,24 @@ export class BootstrapMemories extends Resource {
     let memoriesIncluded = 0;
     let memoriesAvailable = 0;
 
-    // --- 1. Soul records (unconditional — not subject to token budget) ---
-    // Soul is who you are. It's not optional context to be trimmed.
-    // Skill assignments (key='skill-assignment') are separated into their own section.
+    // --- 1. Soul records (budgeted — prioritized by key importance) ---
+    // Soul is who you are, but we still need to respect token budgets.
+    // Workspace files (SOUL.md, AGENTS.md) can be massive — they're already
+    // injected by the runtime via workspace context, so we prioritize
+    // concise soul entries over full file dumps.
+    const SOUL_KEY_PRIORITY: Record<string, number> = {
+      role: 0, identity: 1, thinking: 2, communication_style: 3,
+      team: 4, ownership: 5, infrastructure: 6, "user-context": 7,
+      // Full workspace files — lowest priority (runtime already injects these)
+      soul: 90, "workspace-rules": 91,
+    };
+
     const skillAssignments: any[] = [];
+    const soulMaxTokens = Math.floor(maxTokens * 0.4); // 40% of budget for soul
     if (includeSoul) {
       let soulTokens = 0;
+      const soulEntries: { key: string; line: string; tokens: number; priority: number }[] = [];
+
       for await (const record of (databases as any).flair.Soul.search()) {
         if (record.agentId !== agentId) continue;
         if (record.key === "skill-assignment") {
@@ -81,11 +93,30 @@ export class BootstrapMemories extends Resource {
           continue;
         }
         const line = `**${record.key}:** ${record.value}`;
-        sections.soul.push(line);
-        soulTokens += estimateTokens(line);
+        const tokens = estimateTokens(line);
+        const priority = SOUL_KEY_PRIORITY[record.key] ?? 50;
+        soulEntries.push({ key: record.key, line, tokens, priority });
+      }
+
+      // Sort by priority (lower = more important)
+      soulEntries.sort((a, b) => a.priority - b.priority);
+
+      for (const entry of soulEntries) {
+        if (soulTokens + entry.tokens > soulMaxTokens) {
+          // Skip large entries that exceed budget — truncate or skip
+          if (entry.priority >= 90) continue; // skip full workspace files
+          // Truncate if it's important but too long
+          const maxChars = (soulMaxTokens - soulTokens) * 4;
+          if (maxChars > 100) {
+            const truncated = `**${entry.key}:** ${entry.line.slice(entry.key.length + 6, entry.key.length + 6 + maxChars)}…(truncated)`;
+            sections.soul.push(truncated);
+            soulTokens += estimateTokens(truncated);
+          }
+          continue;
+        }
+        sections.soul.push(entry.line);
+        soulTokens += entry.tokens;
       }
-      // Soul tokens are tracked but don't reduce memory budget
-      tokenBudget = maxTokens; // memory budget is separate from soul
     }
 
     // --- 1b. Skill assignments (ordered by priority, conflict detection) ---
@@ -147,19 +178,28 @@ export class BootstrapMemories extends Resource {
       }
     }
 
-    // --- 3. Recent memories (last 24-48h, standard + persistent) ---
-    const sinceDate = since
-      ? new Date(since)
-      : new Date(Date.now() - 48 * 3600_000);
-    const recent = activeMemories
-      .filter(
-        (m) =>
-          m.durability !== "permanent" &&
-          m.createdAt &&
-          new Date(m.createdAt) >= sinceDate
-      )
+    // --- 3. Recent memories (adaptive window) ---
+    // Start with 48h. If nothing found, widen to 7d, then 30d.
+    // This prevents empty recent sections for agents that were idle.
+    const nonPermanent = activeMemories
+      .filter((m) => m.durability !== "permanent" && m.createdAt)
       .sort((a: any, b: any) => (b.createdAt || "").localeCompare(a.createdAt || ""));
 
+    let effectiveSince: Date;
+    if (since) {
+      effectiveSince = new Date(since);
+    } else {
+      const windows = [48 * 3600_000, 7 * 24 * 3600_000, 30 * 24 * 3600_000];
+      effectiveSince = new Date(Date.now() - windows[0]);
+      for (const w of windows) {
+        effectiveSince = new Date(Date.now() - w);
+        const count = nonPermanent.filter((m) => new Date(m.createdAt!) >= effectiveSince).length;
+        if (count >= 3) break; // found enough recent memories
+      }
+    }
+
+    const recent = nonPermanent.filter((m) => new Date(m.createdAt!) >= effectiveSince);
+
     // Budget: up to 40% of remaining for recent
     const recentBudget = Math.floor(tokenBudget * 0.4);
     let recentSpent = 0;

package/resources/MemoryMaintenance.ts

@@ -0,0 +1,95 @@
+/**
+ * MemoryMaintenance.ts — Maintenance worker for memory hygiene.
+ *
+ * POST /MemoryMaintenance/ — runs cleanup tasks:
+ *   1. Delete expired ephemeral memories (expiresAt < now)
+ *   2. Archive old session memories (> 30 days, standard durability)
+ *   3. Report stats
+ *
+ * Designed to run periodically (daily cron or heartbeat).
+ * Requires admin auth.
+ */
+
+export default class MemoryMaintenance {
+  static ROUTE = "MemoryMaintenance";
+  static METHOD = "POST";
+
+  async post(data: any) {
+    const { databases }: any = this;
+    const request = (this as any).request;
+    const { dryRun = false, agentId } = data || {};
+
+    // Scope to authenticated agent. Admin can pass agentId for system-wide
+    // maintenance; non-admin always scoped to their own agent.
+    const authAgent = request?.headers?.get?.("x-tps-agent");
+    const isAdmin = (request as any)?.tpsAgentIsAdmin === true;
+    const targetAgent = isAdmin && agentId ? agentId : authAgent;
+
+    if (!targetAgent && !isAdmin) {
+      return { error: "agentId required" };
+    }
+
+    const now = new Date();
+    const stats = { expired: 0, archived: 0, total: 0, errors: 0, agent: targetAgent || "all" };
+
+    try {
+      for await (const record of (databases as any).flair.Memory.search()) {
+        // Skip records not belonging to target agent (unless admin running system-wide)
+        if (targetAgent && record.agentId !== targetAgent) continue;
+        stats.total++;
+
+        // 1. Delete expired memories
+        if (record.expiresAt && new Date(record.expiresAt) < now) {
+          if (!dryRun) {
+            try {
+              await (databases as any).flair.Memory.delete(record.id);
+              stats.expired++;
+            } catch {
+              stats.errors++;
+            }
+          } else {
+            stats.expired++;
+          }
+          continue;
+        }
+
+        // 2. Archive old standard session memories (> 30 days)
+        // These are low-value session notes that weren't promoted to persistent.
+        // Archiving removes them from search results but keeps the data.
+        if (
+          record.durability === "standard" &&
+          record.type === "session" &&
+          !record.archived &&
+          record.createdAt
+        ) {
+          const ageMs = now.getTime() - new Date(record.createdAt).getTime();
+          const ageDays = ageMs / (24 * 3600_000);
+          if (ageDays > 30) {
+            if (!dryRun) {
+              try {
+                // Soft archive — set archived flag, keep data
+                await (databases as any).flair.Memory.update(record.id, {
+                  ...record,
+                  archived: true,
+                  archivedAt: now.toISOString(),
+                });
+                stats.archived++;
+              } catch {
+                stats.errors++;
+              }
+            } else {
+              stats.archived++;
+            }
+          }
+        }
+      }
+    } catch (err: any) {
+      return { error: err.message, stats };
+    }
+
+    return {
+      message: dryRun ? "Dry run complete" : "Maintenance complete",
+      stats,
+    };
+  }
+}

package/resources/SemanticSearch.ts

@@ -52,7 +52,7 @@ function compositeScore(
 
 export class SemanticSearch extends Resource {
   async post(data: any) {
-    const { agentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "composite" } = data || {};
+    const { agentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "composite", minScore = 0, since } = data || {};
     const subjectFilter = subjects
       ? new Set((subjects as string[]).map((s: string) => s.toLowerCase()))
       : subject
@@ -94,6 +94,33 @@ export class SemanticSearch extends Resource {
       }
     }
 
+    // ─── Temporal intent detection ────────────────────────────────────────────
+    // If the query implies a time window and no explicit `since` was provided,
+    // auto-detect and apply a recency boost.
+    let sinceDate: Date | null = since ? new Date(since) : null;
+    let temporalBoost = 1.0;
+    if (q && !sinceDate) {
+      const lq = String(q).toLowerCase();
+      if (/\btoday\b|\bthis morning\b|\bthis afternoon\b/.test(lq)) {
+        const d = new Date(); d.setHours(0, 0, 0, 0);
+        sinceDate = d;
+        temporalBoost = 1.5; // boost recent results for temporal queries
+      } else if (/\byesterday\b/.test(lq)) {
+        const d = new Date(); d.setDate(d.getDate() - 1); d.setHours(0, 0, 0, 0);
+        sinceDate = d;
+        temporalBoost = 1.3;
+      } else if (/\bthis week\b|\blast few days\b/.test(lq)) {
+        sinceDate = new Date(Date.now() - 7 * 24 * 3600_000);
+        temporalBoost = 1.2;
+      } else if (/\blast week\b/.test(lq)) {
+        sinceDate = new Date(Date.now() - 14 * 24 * 3600_000);
+        temporalBoost = 1.1;
+      } else if (/\brecently\b|\blately\b/.test(lq)) {
+        sinceDate = new Date(Date.now() - 3 * 24 * 3600_000);
+        temporalBoost = 1.3;
+      }
+    }
+
     const results: any[] = [];
 
     // Iterate ALL memories, filter by agent ID set
@@ -103,22 +130,30 @@ export class SemanticSearch extends Resource {
         if (record.visibility !== "office") continue;
       }
 
-      if (record.archived === true) continue; // soft-deleted — excluded from search by default
+      if (record.archived === true) continue;
       if (record.expiresAt && Date.parse(record.expiresAt) < Date.now()) continue;
       if (tag && !(record.tags || []).includes(tag)) continue;
       if (subjectFilter && record.subject && !subjectFilter.has(String(record.subject).toLowerCase())) continue;
+      // Time window filter
+      if (sinceDate && record.createdAt && new Date(record.createdAt) < sinceDate) continue;
 
-      let rawScore = 0;
+      let semanticScore = 0;
+      let keywordHit = false;
       if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
-        rawScore += 0.5;
+        keywordHit = true;
       }
       if (qEmb && record.embedding && qEmb.length === record.embedding.length) {
-        rawScore += cosineSimilarity(qEmb, record.embedding);
+        semanticScore = cosineSimilarity(qEmb, record.embedding);
       }
+      // Keyword match is a small tiebreaker (5%), not a primary signal.
+      // This prevents weak semantic matches from ranking high just because
+      // a query word appears in the content.
+      const rawScore = semanticScore + (keywordHit ? 0.05 : 0);
       if (q && rawScore === 0) continue;
 
-      // Apply composite scoring (temporal decay + durability + retrieval boost)
-      const finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+      // Apply composite scoring (temporal decay + durability + retrieval boost + temporal intent)
+      let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+      if (temporalBoost > 1.0) finalScore *= temporalBoost;
 
       const { embedding, ...rest } = record;
       results.push({
@@ -139,6 +174,11 @@ export class SemanticSearch extends Resource {
       filteredResults = results.filter((r: any) => !supersededIds.has(r.id));
     }
 
+    // Apply minimum score filter
+    if (minScore > 0) {
+      filteredResults = filteredResults.filter((r: any) => r._score >= minScore);
+    }
+
     filteredResults.sort((a: any, b: any) => b._score - a._score);
     const topResults = filteredResults.slice(0, limit);