Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

feat: manage bot memories with Engram

leepokaicbbee60dfbcf
diff --git a/.github/workflows/host.yml b/.github/workflows/host.yml
index da1e0ac0..8c896a66 100644
--- a/.github/workflows/host.yml
+++ b/.github/workflows/host.yml
@@ -4,7 +4,7 @@ on:
push:
tags: ["v*"] # one version tag ships the host and the desktop app (release-desktop.yml)
pull_request:
- paths: ["host/**", "packaging/updates/**", "docs/reference/fixtures/remote-relay-vectors.json", ".github/workflows/host.yml"]
+ paths: ["host/**", "packaging/updates/**", "packaging/engram/**", "docs/reference/fixtures/remote-relay-vectors.json", ".github/workflows/host.yml"]
# A newer push to the same PR supersedes the run in progress; tag runs always finish.
concurrency:
@@ -32,7 +32,11 @@ jobs:
workspaces: host
- run: cargo fmt --check
- run: cargo clippy --all-targets -- -D warnings
+ - name: Fetch pinned memory runtime for integration tests
+ run: python ../packaging/engram/test-runtime.py
- run: cargo test
+ - run: cargo test --test memory_e2e -- --ignored
+ - run: cargo test --bin codync-host native_memory_survives_restart -- --ignored
release:
if: startsWith(github.ref, 'refs/tags/v')
diff --git a/apps/desktop/src/renderer/store/memory-store.ts b/apps/desktop/src/renderer/store/memory-store.ts
new file mode 100644
index 00000000..6f7fada1
--- /dev/null
+++ b/apps/desktop/src/renderer/store/memory-store.ts
@@ -0,0 +1,150 @@
+import type { HostClient } from '../client/host-client'
+import { Observable } from '../lib/observable'
+
+export interface MemoryFact {
+ id: string
+ title: string
+ content: string
+ createdAt: number
+ kind: string
+ memoryType: string
+ scope: string
+ topicKey: string | null
+ pinned: boolean
+ reviewAfter: string | null
+ revisionCount: number
+ source: string | null
+}
+
+export interface MemoryDraft {
+ id?: string
+ title: string
+ content: string
+ scope: string
+ memoryType: string
+ topicKey: string
+}
+
+interface Listing { facts: MemoryFact[]; total: number; nextOffset: number | null }
+export interface MemoryDetail {
+ fact: MemoryFact
+ history: { result: string; history?: { version: number; title: string; content: string; created_at: string }[]; history_cursor?: number }
+ timeline: { result: string }
+}
+
+/** Owns requests, errors and stale-response protection for one bot's memory. */
+export class MemoryStore extends Observable {
+ facts: MemoryFact[] = []
+ query = ''
+ filter = 'all'
+ total = 0
+ nextOffset: number | null = null
+ loaded = false
+ busy = false
+ error: string | null = null
+ detail: MemoryDetail | null = null
+ backup = ''
+ private request = 0
+ private detailRequest = 0
+ private searchTimer?: ReturnType<typeof setTimeout>
+
+ constructor(readonly botId: string, private readonly client: () => Promise<HostClient>) { super() }
+
+ async load(more = false) {
+ const request = ++this.request
+ const offset = more ? this.nextOffset : 0
+ if (offset === null) return
+ this.error = null
+ this.changed()
+ try {
+ const listing = await (await this.client()).call<Listing>('memory', {
+ botId: this.botId, query: this.query, filter: this.filter, offset,
+ }, 240_000)
+ if (request !== this.request) return
+ this.facts = more ? [...this.facts, ...listing.facts] : listing.facts
+ this.total = listing.total
+ this.nextOffset = listing.nextOffset
+ this.loaded = true
+ } catch (error) {
+ if (request === this.request) this.error = message(error)
+ }
+ this.changed()
+ }
+
+ search(query: string, filter = this.filter) {
+ this.query = query
+ this.filter = filter
+ ++this.request
+ clearTimeout(this.searchTimer)
+ this.searchTimer = setTimeout(() => { void this.load() }, 250)
+ }
+
+ async mutate(method: string, body: object = {}) {
+ if (this.busy) return false
+ return this.perform(async () => {
+ await (await this.client()).call(method, { botId: this.botId, ...body }, 240_000)
+ })
+ }
+
+ private async perform(work: () => Promise<void>) {
+ if (this.busy) return false
+ this.busy = true
+ this.error = null
+ this.changed()
+ try {
+ await work()
+ await this.load()
+ return true
+ } catch (error) {
+ this.error = message(error)
+ return false
+ } finally {
+ this.busy = false
+ this.changed()
+ }
+ }
+
+ async inspect(fact: MemoryFact, cursor?: number) {
+ const request = ++this.detailRequest
+ this.error = null
+ if (!cursor) this.detail = null
+ this.changed()
+ try {
+ const detail = await (await this.client()).call<MemoryDetail>('memoryDetail', {
+ botId: this.botId, id: fact.id, ...(cursor ? { historyCursor: cursor } : {}),
+ }, 240_000)
+ if (request === this.detailRequest) this.detail = detail
+ } catch (error) { if (request === this.detailRequest) this.error = message(error) }
+ this.changed()
+ }
+
+ async export() {
+ this.error = null
+ this.backup = ''
+ this.changed()
+ try {
+ const client = await this.client()
+ const result = await client.call<{ json?: string; uploadId?: string }>('exportMemory', { botId: this.botId }, 240_000)
+ this.backup = result.uploadId ? new TextDecoder('utf-8', { fatal: true }).decode(await client.readUpload(this.botId, result.uploadId)) : result.json ?? ''
+ } catch (error) { this.error = message(error) }
+ this.changed()
+ }
+
+ async import(text: string) {
+ try { JSON.parse(text) }
+ catch { this.error = 'Enter a valid Engram JSON backup.'; this.changed(); return false }
+ return this.perform(async () => {
+ const data = new TextEncoder().encode(text)
+ const client = await this.client()
+ if (data.length <= 384 * 1024) {
+ await client.call('importMemory', { botId: this.botId, json: text }, 240_000)
+ } else {
+ const uploadId = crypto.randomUUID()
+ await client.upload(this.botId, uploadId, 'engram-backup.json', data)
+ await client.call('importMemory', { botId: this.botId, uploadId }, 240_000)
+ }
+ })
+ }
+}
+
+function message(error: unknown) { return error instanceof Error ? error.message : String(error) }
diff --git a/apps/desktop/src/renderer/views/bots/MemoryView.tsx b/apps/desktop/src/renderer/views/bots/MemoryView.tsx
index be8595f5..64b96daa 100644
--- a/apps/desktop/src/renderer/views/bots/MemoryView.tsx
+++ b/apps/desktop/src/renderer/views/bots/MemoryView.tsx
@@ -1,87 +1,89 @@
-import { useCallback, useEffect, useState } from 'react'
-import { CardSection } from '../../components/Controls'
-import { Icon } from '../../components/Icon'
-import { Dialog } from '../../components/Overlay'
+import { useEffect, useMemo, useState } from 'react'
+import { Button, CardSection } from '../../components/Controls'
+import { Dialog, ModalHeader, Sheet } from '../../components/Overlay'
+import { useModel } from '../../lib/observable'
import { useStore } from '../../store/context'
-import './bots.css'
+import { MemoryStore, type MemoryDraft, type MemoryFact } from '../../store/memory-store'
+import './memory.css'
-/** One remembered fact (host `memory` API). */
-interface MemoryFact {
- id: string
- content: string
- createdAt: number
- /** `profile` (who the user is) or `log` (dated history). */
- kind: string
-}
-
-/**
- * What the bot remembers about the user, in the bot's settings. Facts are
- * learned after each exchange and survive new sessions; remove any here.
- */
export function MemoryCard({ botId }: { botId: string }) {
- const store = useStore()
- const client = store.client
- const [facts, setFacts] = useState<MemoryFact[]>([])
- const [loaded, setLoaded] = useState(false)
+ const host = useStore()
+ const memory = useModel(useMemo(() => new MemoryStore(botId, () => host.ready()), [botId, host]))
+ const [draft, setDraft] = useState<MemoryDraft | null>(null)
+ const [showDetail, setShowDetail] = useState(false)
+ const [backupMode, setBackupMode] = useState<'export' | 'import' | null>(null)
+ const [importText, setImportText] = useState('')
const [confirmClear, setConfirmClear] = useState(false)
+ useEffect(() => { void memory.load() }, [memory])
- const load = useCallback(async () => {
- if (!client) return
- try {
- setFacts((await client.call<{ location: string; facts: MemoryFact[] }>('memory', { botId })).facts)
- } catch {
- setFacts([])
- }
- setLoaded(true)
- }, [client, botId])
-
- useEffect(() => {
- void load()
- }, [load])
-
- const forget = (fact: MemoryFact) => {
- setFacts((list) => list.filter((f) => f.id !== fact.id))
- void client?.call('forgetMemory', { botId, id: fact.id }).catch(() => {}).then(load)
- }
-
- const clear = () => {
- setFacts([])
- void client?.call('clearMemory', { botId }).catch(() => {}).then(load)
- }
+ const edit = (fact?: MemoryFact) => setDraft({
+ id: fact?.id, title: fact?.title ?? '', content: fact?.content ?? '',
+ scope: fact?.scope ?? 'project', memoryType: fact?.memoryType ?? 'learning', topicKey: fact?.topicKey ?? '',
+ })
- return (
- <>
- <CardSection
- title="Memory"
- accessory={
- facts.length ? (
- <button className="press" style={{ display: 'flex', color: 'var(--secondary)' }} title="Forget everything" aria-label="Forget everything" onClick={() => setConfirmClear(true)}>
- <Icon name="trash" size={12} />
- </button>
- ) : null
- }
- >
- {facts.length ? null : (
- <span style={{ color: 'var(--secondary)' }}>{loaded ? 'Nothing yet. The bot remembers who you are and what you work on as you chat.' : 'Loading…'}</span>
- )}
- {facts.map((fact) => (
- <div key={fact.id} className="fade-in" style={{ display: 'flex', alignItems: 'baseline', gap: 10 }}>
- <span style={{ display: 'flex' }} title={fact.kind === 'profile' ? 'About you' : 'History'}>
- <Icon name={fact.kind === 'profile' ? 'person' : 'clock'} size={10} color="var(--tertiary)" />
- </span>
- <span className="selectable" style={{ flex: 1, minWidth: 0, color: 'var(--text)' }}>{fact.content}</span>
- <button className="press" style={{ display: 'flex', color: 'var(--tertiary)' }} title="Forget" aria-label="Forget" onClick={() => forget(fact)}>
- <Icon name="xmark" size={10} />
- </button>
- </div>
- ))}
- </CardSection>
- <Dialog
- open={confirmClear}
- title="Forget everything this bot remembers?"
- actions={[{ title: 'Forget everything', destructive: true, action: clear }]}
- onClose={() => setConfirmClear(false)}
- />
- </>
- )
+ return <>
+ <CardSection title="Memory" accessory={<button className="press" onClick={() => edit()} disabled={memory.busy}>Add</button>}>
+ <div className="memory-actions">
+ <input aria-label="Search memories" placeholder="Search memories" value={memory.query} onChange={e => memory.search(e.target.value)} />
+ <button className="press" onClick={() => void memory.load()}>Refresh</button>
+ </div>
+ <div className="memory-actions" role="group" aria-label="Memory filter">
+ {(['all', 'profile', 'pinned', 'review'] as const).map(filter => <button key={filter} className="press" aria-pressed={memory.filter === filter}
+ onClick={() => memory.search(memory.query, filter)}>{({ all: 'All', profile: 'About you', pinned: 'Pinned', review: 'Needs review' })[filter]}</button>)}
+ </div>
+ {memory.error && <p role="alert" className="memory-error">{memory.error}</p>}
+ {!memory.loaded && !memory.error && <p>Loading memory…</p>}
+ {memory.loaded && !memory.facts.length && <p className="memory-muted">{memory.query || memory.filter !== 'all' ? 'No matching memories.' : 'Nothing yet. Important details are remembered as you chat.'}</p>}
+ {memory.facts.map(fact => <div className="memory-item fade-in" key={fact.id}>
+ <button className="press memory-content" onClick={() => edit(fact)}>
+ <strong>{fact.pinned ? '● ' : ''}{fact.title}</strong>
+ <span>{fact.content}</span>
+ <small>{fact.kind === 'profile' ? 'About you' : fact.memoryType} · {new Date(fact.createdAt).toLocaleDateString()} · {fact.revisionCount} revisions</small>
+ </button>
+ <div className="memory-actions">
+ <button className="press" onClick={() => void memory.mutate('pinMemory', { id: fact.id, pinned: !fact.pinned })} disabled={memory.busy}>{fact.pinned ? 'Unpin' : 'Pin'}</button>
+ <button className="press" onClick={() => { setShowDetail(true); void memory.inspect(fact) }}>History</button>
+ {fact.reviewAfter && <button className="press" onClick={() => void memory.mutate('reviewMemory', { id: fact.id })} disabled={memory.busy}>Mark reviewed</button>}
+ <button className="press" onClick={() => void memory.mutate('forgetMemory', { id: fact.id })} disabled={memory.busy}>Forget</button>
+ </div>
+ </div>)}
+ {memory.nextOffset !== null && <button className="press" onClick={() => void memory.load(true)}>Load more ({memory.total})</button>}
+ <div className="memory-actions">
+ <button className="press" onClick={() => { setBackupMode('export'); void memory.export() }}>Export</button>
+ <button className="press" onClick={() => setBackupMode('import')}>Import</button>
+ <button className="press" onClick={() => setConfirmClear(true)} disabled={memory.busy}>Forget everything</button>
+ </div>
+ </CardSection>
+ <Sheet open={draft !== null} onClose={() => setDraft(null)} width={560}>
+ <ModalHeader title={draft?.id ? 'Edit memory' : 'Add memory'} />
+ {draft && <div className="memory-editor">
+ <label>Title<input value={draft.title} onChange={e => setDraft({ ...draft, title: e.target.value })} /></label>
+ <label>Memory<textarea rows={8} value={draft.content} onChange={e => setDraft({ ...draft, content: e.target.value })} /></label>
+ <div className="memory-actions">{['project', 'personal', 'global'].map(scope => <button className="press" key={scope} aria-pressed={draft.scope === scope} onClick={() => setDraft({ ...draft, scope })}>{scope === 'personal' ? 'About you' : scope === 'global' ? 'General' : 'Work'}</button>)}</div>
+ <label>Category<input value={draft.memoryType} onChange={e => setDraft({ ...draft, memoryType: e.target.value })} /></label>
+ <label>Topic (optional)<input value={draft.topicKey} onChange={e => setDraft({ ...draft, topicKey: e.target.value })} /></label>
+ {memory.error && <p role="alert" className="memory-error">{memory.error}</p>}
+ <Button disabled={memory.busy || !draft.title.trim() || !draft.content.trim()} onClick={() => { void memory.mutate('saveMemory', draft).then(saved => { if (saved) setDraft(null) }) }}>{memory.busy ? 'Saving…' : 'Save'}</Button>
+ </div>}
+ </Sheet>
+ <Sheet open={showDetail} onClose={() => setShowDetail(false)} width={620}>
+ <ModalHeader title="Memory history" />
+ <div className="memory-editor">
+ {memory.error && <p className="memory-error">{memory.error}</p>}
+ {memory.detail ? <><pre className="memory-history">{memory.detail.history.result}</pre>
+ {memory.detail.history.history_cursor && <button className="press" onClick={() => void memory.inspect(memory.detail!.fact, memory.detail!.history.history_cursor)}>Older versions</button>}
+ <h4>Session timeline</h4><pre className="memory-history">{memory.detail.timeline.result}</pre></> : <p>Loading history…</p>}
+ </div>
+ </Sheet>
+ <Sheet open={backupMode !== null} onClose={() => setBackupMode(null)} width={620}>
+ <ModalHeader title={backupMode === 'export' ? 'Export memories' : 'Import memories'} />
+ <div className="memory-editor">
+ <p>{backupMode === 'export' ? 'Copy this Engram backup to keep or import your memories.' : 'Paste an Engram JSON backup. Import merges memories and preserves newer changes. A backup is saved first.'}</p>
+ <textarea aria-label="Memory backup" rows={14} readOnly={backupMode === 'export'} value={backupMode === 'export' ? memory.backup : importText} onChange={e => setImportText(e.target.value)} />
+ {memory.error && <p className="memory-error">{memory.error}</p>}
+ {backupMode === 'import' && <Button disabled={memory.busy || !importText.trim()} onClick={() => { void memory.import(importText).then(ok => { if (ok) setBackupMode(null) }) }}>Import</Button>}
+ </div>
+ </Sheet>
+ <Dialog open={confirmClear} title="Forget everything this bot remembers?" actions={[{ title: 'Forget everything', destructive: true, action: () => { void memory.mutate('clearMemory') } }]} onClose={() => setConfirmClear(false)} />
+ </>
}
diff --git a/apps/desktop/src/renderer/views/bots/memory.css b/apps/desktop/src/renderer/views/bots/memory.css
new file mode 100644
index 00000000..aab56d3c
--- /dev/null
+++ b/apps/desktop/src/renderer/views/bots/memory.css
@@ -0,0 +1,14 @@
+.memory-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
+.memory-actions button { color: var(--secondary); font-size: 12px; }
+.memory-actions button[aria-pressed="true"] { color: var(--text); font-weight: 650; }
+.memory-actions input { flex: 1; min-width: 100px; }
+.memory-item { padding: 8px 0; }
+.memory-content { display: flex; flex-direction: column; gap: 4px; width: 100%; text-align: left; margin-bottom: 8px; }
+.memory-content span { white-space: pre-wrap; overflow-wrap: anywhere; display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+.memory-content small, .memory-muted { color: var(--secondary); }
+.memory-editor { display: flex; flex-direction: column; gap: 16px; padding: 20px; max-height: 70vh; overflow: auto; }
+.memory-editor label { display: flex; flex-direction: column; gap: 6px; }
+.memory-editor input, .memory-editor textarea, .memory-actions input { padding: 10px; background: var(--surface); color: var(--text); border: 0; border-radius: 8px; font: inherit; }
+.memory-editor textarea { resize: vertical; }
+.memory-history { white-space: pre-wrap; overflow-wrap: anywhere; font: inherit; user-select: text; }
+.memory-error { color: var(--danger, #df665e); white-space: pre-wrap; }
diff --git a/apps/desktop/src/shared/compat.test.ts b/apps/desktop/src/shared/compat.test.ts
index ed97ee46..39820db5 100644
--- a/apps/desktop/src/shared/compat.test.ts
+++ b/apps/desktop/src/shared/compat.test.ts
@@ -13,6 +13,6 @@ test('versions parse like the host and the iPhone app', () => {
test('the side that must update', () => {
assert.deepEqual(checkVersions('2.6.0', '2.7.0', '2.7.0'), { kind: 'updateApp', minimum: '2.7.0' })
- assert.deepEqual(checkVersions('2.7.0', '2.2.0', null), { kind: 'updateHost', version: '2.2.0', minimum: '2.3.0' })
- assert.equal(checkVersions('2.7.0', '2.7.0', '2.3.0'), null)
+ assert.deepEqual(checkVersions('2.7.0', '2.2.0', null), { kind: 'updateHost', version: '2.2.0', minimum: '2.12.0' })
+ assert.equal(checkVersions('2.12.0', '2.12.0', '2.3.0'), null)
})
diff --git a/apps/desktop/src/shared/compat.ts b/apps/desktop/src/shared/compat.ts
index a433777d..14fddfd0 100644
--- a/apps/desktop/src/shared/compat.ts
+++ b/apps/desktop/src/shared/compat.ts
@@ -6,7 +6,7 @@ export type VersionMismatch =
| { kind: 'updateHost'; version: string; minimum: string }
/** The oldest host this app works with. */
-export const MIN_HOST = '2.3.0'
+export const MIN_HOST = '2.12.0'
/** `major.minor.patch`, ignoring a leading `v` and any pre-release or build suffix. */
export function parseVersion(version: string): number[] | null {
diff --git a/apps/ios/Kit/Sources/CodyncKit/Models/Compatibility.swift b/apps/ios/Kit/Sources/CodyncKit/Models/Compatibility.swift
index b8bd4453..23a0bc40 100644
--- a/apps/ios/Kit/Sources/CodyncKit/Models/Compatibility.swift
+++ b/apps/ios/Kit/Sources/CodyncKit/Models/Compatibility.swift
@@ -11,7 +11,7 @@ public enum VersionMismatch: Equatable, Sendable {
/// The oldest host this app works with. Raise it only when the app starts depending on
/// something older hosts don't have (an optional feature hides its control instead).
- public static let minHost = "2.3.0"
+ public static let minHost = "2.12.0"
/// Checks this app (`app`) against a host's version and `minApp` (nil from hosts that predate it).
public static func check(app: String, minHost: String = minHost, hostVersion: String, minApp: String?) -> VersionMismatch? {
diff --git a/apps/ios/Kit/Sources/CodyncKit/Models/Memory.swift b/apps/ios/Kit/Sources/CodyncKit/Models/Memory.swift
new file mode 100644
index 00000000..b11e3331
--- /dev/null
+++ b/apps/ios/Kit/Sources/CodyncKit/Models/Memory.swift
@@ -0,0 +1,97 @@
+import Foundation
+
+public struct MemoryFact: Codable, Identifiable, Hashable, Sendable {
+ public var id: String
+ public var title: String
+ public var content: String
+ public var createdAt: Int64
+ public var kind: String
+ public var memoryType: String
+ public var scope: String
+ public var topicKey: String?
+ public var pinned: Bool
+ public var reviewAfter: String?
+ public var revisionCount: Int
+ public var source: String?
+}
+
+public struct MemoryListing: Decodable, Sendable {
+ public var facts: [MemoryFact]
+ public var total: Int
+ public var nextOffset: Int?
+}
+
+public struct MemoryDetail: Decodable, Sendable {
+ public var fact: MemoryFact
+ public var history: History
+ public var timeline: Timeline
+
+ public struct History: Decodable, Sendable {
+ public var result: String
+ public var history_cursor: Int?
+ }
+ public struct Timeline: Decodable, Sendable { public var result: String }
+}
+
+public struct MemoryDraft: Encodable, Sendable {
+ public var botId: String
+ public var id: String?
+ public var title: String
+ public var content: String
+ public var scope: String
+ public var memoryType: String
+ public var topicKey: String
+
+ public init(botId: String, fact: MemoryFact? = nil) {
+ self.botId = botId
+ id = fact?.id
+ title = fact?.title ?? ""
+ content = fact?.content ?? ""
+ scope = fact?.scope ?? "project"
+ memoryType = fact?.memoryType ?? "learning"
+ topicKey = fact?.topicKey ?? ""
+ }
+}
+
+extension HostClient {
+ public func memory(botId: String, query: String = "", filter: String = "all", offset: Int = 0) async throws -> MemoryListing {
+ struct Body: Encodable { var botId: String; var query: String; var filter: String; var offset: Int }
+ return try await call("memory", Body(botId: botId, query: query, filter: filter, offset: offset), timeout: 240)
+ }
+
+ public func saveMemory(_ draft: MemoryDraft) async throws {
+ let _: Empty = try await call("saveMemory", draft, timeout: 240)
+ }
+
+ public func memoryAction(_ method: String, botId: String, id: String? = nil, pinned: Bool? = nil) async throws {
+ struct Body: Encodable { var botId: String; var id: String?; var pinned: Bool? }
+ let _: Empty = try await call(method, Body(botId: botId, id: id, pinned: pinned), timeout: 240)
+ }
+
+ public func memoryDetail(botId: String, id: String, cursor: Int? = nil) async throws -> MemoryDetail {
+ struct Body: Encodable { var botId: String; var id: String; var historyCursor: Int? }
+ return try await call("memoryDetail", Body(botId: botId, id: id, historyCursor: cursor), timeout: 240)
+ }
+
+ public func exportMemory(botId: String) async throws -> String {
+ struct Response: Decodable { var json: String?; var uploadId: String? }
+ let result: Response = try await call("exportMemory", ["botId": botId], timeout: 240)
+ if let id = result.uploadId {
+ let data = try await readUpload(botId: botId, id: id)
+ guard let text = String(data: data, encoding: .utf8) else { throw CocoaError(.fileReadInapplicableStringEncoding) }
+ return text
+ }
+ return result.json ?? ""
+ }
+
+ public func importMemory(botId: String, json: String) async throws {
+ let data = Data(json.utf8)
+ if data.count > 384 * 1024 {
+ let id = UUID().uuidString.lowercased()
+ try await upload(botId: botId, id: id, name: "engram-backup.json", data: data)
+ let _: Empty = try await call("importMemory", ["botId": botId, "uploadId": id], timeout: 240)
+ } else {
+ let _: Empty = try await call("importMemory", ["botId": botId, "json": json], timeout: 240)
+ }
+ }
+}
diff --git a/apps/ios/Kit/Sources/CodyncKit/Models/Models.swift b/apps/ios/Kit/Sources/CodyncKit/Models/Models.swift
index 7ecbd075..2978abc9 100644
--- a/apps/ios/Kit/Sources/CodyncKit/Models/Models.swift
+++ b/apps/ios/Kit/Sources/CodyncKit/Models/Models.swift
@@ -336,54 +336,6 @@ public struct Hello: Codable, Sendable {
public var cloud: String?
}
-/// The computer's remote screen: whether phones can view/control it, and who's in control.
-public struct ScreenState: Codable, Equatable, Sendable {
- public var enabled = false
- /// The screen helper is running.
- public var connected = false
- public var platform = ""
- /// Screen recording is permitted.
- public var capture = false
- /// Input injection is permitted.
- public var input = false
- public var displays: [ScreenDisplay] = []
- /// A phone took over: bots may only look.
- public var userControl = false
- /// The bot using the computer right now.
- public var agentBot: String?
- /// Bots with computer use can act here (Windows: always; elsewhere Remote screen is on).
- public var computerUse = false
- public var viewers = 0
-
- public init() {}
-
- public var available: Bool { enabled && connected && capture }
- public var mainDisplay: ScreenDisplay? { displays.first(where: \.main) ?? displays.first }
-
- public init(from decoder: Decoder) throws {
- let c = try decoder.container(keyedBy: CodingKeys.self)
- enabled = try c.decodeIfPresent(Bool.self, forKey: .enabled) ?? false
- connected = try c.decodeIfPresent(Bool.self, forKey: .connected) ?? false
- platform = try c.decodeIfPresent(String.self, forKey: .platform) ?? ""
- capture = try c.decodeIfPresent(Bool.self, forKey: .capture) ?? false
- input = try c.decodeIfPresent(Bool.self, forKey: .input) ?? false
- displays = try c.decodeIfPresent([ScreenDisplay].self, forKey: .displays) ?? []
- userControl = try c.decodeIfPresent(Bool.self, forKey: .userControl) ?? false
- agentBot = try c.decodeIfPresent(String.self, forKey: .agentBot)
- computerUse = try c.decodeIfPresent(Bool.self, forKey: .computerUse) ?? enabled
- viewers = try c.decodeIfPresent(Int.self, forKey: .viewers) ?? 0
- }
-}
-
-public struct ScreenDisplay: Codable, Hashable, Identifiable, Sendable {
- public var id: UInt32
- public var name: String
- /// Size in points: the coordinate space of screen input.
- public var width: Double
- public var height: Double
- public var main: Bool
-}
-
public struct SyncResponse: Codable, Sendable {
public var hostId: String
public var rev: Int64
diff --git a/apps/ios/Kit/Sources/CodyncKit/Models/ScreenState.swift b/apps/ios/Kit/Sources/CodyncKit/Models/ScreenState.swift
new file mode 100644
index 00000000..61a1a4ac
--- /dev/null
+++ b/apps/ios/Kit/Sources/CodyncKit/Models/ScreenState.swift
@@ -0,0 +1,71 @@
+import Foundation
+
+/// The computer's remote screen: whether phones can view/control it, and who's in control.
+public struct ScreenState: Codable, Equatable, Sendable {
+ public var enabled = false
+ /// The screen helper is running.
+ public var connected = false
+ public var platform = ""
+ /// App name shown in the computer’s system permission settings.
+ public var permissionApp: String?
+ /// Screen recording is permitted.
+ public var capture = false
+ /// Input injection is permitted.
+ public var input = false
+ public var displays: [ScreenDisplay] = []
+ /// A phone took over: bots may only look.
+ public var userControl = false
+ /// The bot using the computer right now.
+ public var agentBot: String?
+ /// Bots with computer use can act here (Windows: always; elsewhere Remote screen is on).
+ public var computerUse = false
+ public var viewers = 0
+
+ public init() {}
+
+ public var available: Bool { enabled && connected && capture }
+ public var controlReady: Bool { platform == "windows" ? computerUse : available && input }
+ public var mainDisplay: ScreenDisplay? { displays.first(where: \.main) ?? displays.first }
+
+ public init(from decoder: Decoder) throws {
+ let c = try decoder.container(keyedBy: CodingKeys.self)
+ enabled = try c.decodeIfPresent(Bool.self, forKey: .enabled) ?? false
+ connected = try c.decodeIfPresent(Bool.self, forKey: .connected) ?? false
+ platform = try c.decodeIfPresent(String.self, forKey: .platform) ?? ""
+ permissionApp = try c.decodeIfPresent(String.self, forKey: .permissionApp)
+ capture = try c.decodeIfPresent(Bool.self, forKey: .capture) ?? false
+ input = try c.decodeIfPresent(Bool.self, forKey: .input) ?? false
+ displays = try c.decodeIfPresent([ScreenDisplay].self, forKey: .displays) ?? []
+ userControl = try c.decodeIfPresent(Bool.self, forKey: .userControl) ?? false
+ agentBot = try c.decodeIfPresent(String.self, forKey: .agentBot)
+ computerUse = try c.decodeIfPresent(Bool.self, forKey: .computerUse) ?? enabled
+ viewers = try c.decodeIfPresent(Int.self, forKey: .viewers) ?? 0
+ }
+}
+
+public struct ScreenDisplay: Codable, Hashable, Identifiable, Sendable {
+ public var id: UInt32
+ public var name: String
+ /// Size in points: the coordinate space of screen input.
+ public var width: Double
+ public var height: Double
+ public var main: Bool
+}
+
+extension ScreenState {
+ /// Remote clients explain setup; only the computer itself can request OS permissions.
+ public var accessGuidance: String {
+ if platform == "windows" {
+ return "Remote screen viewing is not available on Windows yet. Bots can still use apps on that computer."
+ }
+ let setup = "On the computer, open Codync → Settings → Computer access. Permissions are set separately on each computer."
+ if !enabled { return "Remote screen is off. \(setup)" }
+ if !connected { return "Codync Screen is not running. \(setup)" }
+ if !capture || (platform == "linux" && !input) {
+ if platform == "linux" { return "Choose a screen and allow control in the system sharing dialog. \(setup)" }
+ return "Allow screen recording for \(permissionApp ?? "Codync Screen"). \(setup)"
+ }
+ if !input { return "Allow computer control for \(permissionApp ?? "Codync Screen"). macOS may call this Device Control and Data Access or Accessibility. \(setup)" }
+ return "Computer access is ready."
+ }
+}
diff --git a/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryBackupView.swift b/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryBackupView.swift
new file mode 100644
index 00000000..5bd728d2
--- /dev/null
+++ b/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryBackupView.swift
@@ -0,0 +1,31 @@
+import CodyncKit
+import SwiftUI
+
+enum MemoryBackupMode: String, Identifiable { case export, `import`; var id: String { rawValue } }
+
+struct MemoryBackupView: View {
+ let memory: MemoryStore
+ let mode: MemoryBackupMode
+ @State private var text = ""
+ @Environment(\.dismissModal) private var dismiss
+
+ var body: some View {
+ VStack(spacing: 0) {
+ ModalHeader(mode == .export ? "Export memories" : "Import memories") { EmptyView() }
+ ScrollView {
+ VStack(alignment: .leading, spacing: 16) {
+ Text(mode == .export ? "Copy this Engram backup to keep or import your memories." : "Paste an Engram JSON backup. Import merges memories and preserves newer changes. A backup is saved first.")
+ if mode == .export {
+ Text(memory.backup.isEmpty ? "Preparing backup…" : memory.backup).font(.caption.monospaced()).textSelection(.enabled)
+ } else {
+ TextEditor(text: $text).frame(minHeight: 280).scrollContentBackground(.hidden)
+ .padding(10).background(Palette.surface, in: RoundedRectangle(cornerRadius: 12))
+ Button("Import") { Task { if await memory.importBackup(text) { dismiss() } } }
+ .buttonStyle(PrimaryButtonStyle()).disabled(memory.busy || text.isEmpty)
+ }
+ if let error = memory.error { Text(error).foregroundStyle(Palette.danger) }
+ }.padding(20)
+ }
+ }
+ }
+}
diff --git a/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryEditorView.swift b/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryEditorView.swift
new file mode 100644
index 00000000..183cc22a
--- /dev/null
+++ b/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryEditorView.swift
@@ -0,0 +1,46 @@
+import CodyncKit
+import SwiftUI
+
+struct MemoryEditorView: View {
+ let memory: MemoryStore
+ @State var draft: MemoryDraft
+ @Environment(\.dismissModal) private var dismiss
+
+ var body: some View {
+ VStack(spacing: 0) {
+ ModalHeader(draft.id == nil ? "Add memory" : "Edit memory") { EmptyView() }
+ ScrollView {
+ VStack(alignment: .leading, spacing: 16) {
+ field("Title", text: $draft.title)
+ Text("Memory").font(.caption).foregroundStyle(Palette.secondary)
+ TextEditor(text: $draft.content).frame(minHeight: 160).scrollContentBackground(.hidden)
+ .padding(10).background(Palette.surface, in: RoundedRectangle(cornerRadius: 12))
+ HStack(spacing: 14) {
+ ForEach(["project", "personal", "global"], id: \.self) { scope in
+ Button(scope == "personal" ? "About you" : scope == "global" ? "General" : "Work") {
+ withAnimation(Motion.layout) { draft.scope = scope }
+ }
+ .fontWeight(draft.scope == scope ? .semibold : .regular)
+ }
+ }.buttonStyle(.plain)
+ field("Category", text: $draft.memoryType)
+ field("Topic (optional)", text: $draft.topicKey)
+ if let error = memory.error { Text(error).foregroundStyle(Palette.danger) }
+ Button(memory.busy ? "Saving…" : "Save") {
+ Task { if await memory.save(draft) { dismiss() } }
+ }
+ .buttonStyle(PrimaryButtonStyle())
+ .disabled(memory.busy || draft.title.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty || draft.content.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+ }.padding(20)
+ }
+ }
+ }
+
+ private func field(_ title: String, text: Binding<String>) -> some View {
+ VStack(alignment: .leading, spacing: 6) {
+ Text(title).font(.caption).foregroundStyle(Palette.secondary)
+ TextField(title, text: text).textFieldStyle(.plain).plainTextInput()
+ .padding(12).background(Palette.surface, in: RoundedRectangle(cornerRadius: 12))
+ }
+ }
+}
diff --git a/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryHistoryView.swift b/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryHistoryView.swift
new file mode 100644
index 00000000..3db9d054
--- /dev/null
+++ b/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryHistoryView.swift
@@ -0,0 +1,25 @@
+import CodyncKit
+import SwiftUI
+
+struct MemoryHistoryView: View {
+ let memory: MemoryStore
+
+ var body: some View {
+ VStack(spacing: 0) {
+ ModalHeader("Memory history") { EmptyView() }
+ ScrollView {
+ VStack(alignment: .leading, spacing: 16) {
+ if let error = memory.error { Text(error).foregroundStyle(Palette.danger) }
+ if let detail = memory.detail {
+ Text(detail.history.result).textSelection(.enabled)
+ if let cursor = detail.history.history_cursor {
+ Button("Older versions") { Task { await memory.inspect(detail.fact, cursor: cursor) } }.buttonStyle(.plain)
+ }
+ Text("Session timeline").fontWeight(.semibold)
+ Text(detail.timeline.result).textSelection(.enabled)
+ } else { Text("Loading history…").foregroundStyle(Palette.secondary) }
+ }.frame(maxWidth: .infinity, alignment: .leading).padding(20)
+ }
+ }
+ }
+}
diff --git a/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryView.swift b/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryView.swift
index 12e74bd2..605988ad 100644
--- a/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryView.swift
+++ b/apps/ios/Kit/Sources/CodyncUI/Bots/MemoryView.swift
@@ -1,105 +1,120 @@
import CodyncKit
import SwiftUI
-/// One remembered fact (host `memory` API).
-public struct MemoryFact: Codable, Identifiable, Hashable, Sendable {
- public var id: String
- public var content: String
- public var createdAt: Int64
- /// `profile` (who the user is) or `log` (dated history).
- public var kind: String
-}
-
-struct MemoryListing: Codable, Sendable {
- var location: String
- var facts: [MemoryFact]
-}
-
-extension HostClient {
- func memory(botId: String) async throws -> MemoryListing {
- struct Body: Encodable { var botId: String }
- return try await call("memory", Body(botId: botId))
- }
-
- func forgetMemory(botId: String, id: String) async throws {
- struct Body: Encodable { var botId: String; var id: String }
- let _: Empty = try await call("forgetMemory", Body(botId: botId, id: id))
- }
-
- func clearMemory(botId: String) async throws {
- struct Body: Encodable { var botId: String }
- let _: Empty = try await call("clearMemory", Body(botId: botId))
- }
-}
-
-/// What the bot remembers about the user, in the bot's settings. Facts are
-/// learned after each exchange and survive new sessions; remove any here.
struct MemoryCard: View {
let botId: String
- @Environment(BotStore.self) private var model
- @State private var facts: [MemoryFact] = []
- @State private var loaded = false
+ @Environment(BotStore.self) private var host
+ @State private var memory: MemoryStore?
+ @State private var editor: MemoryEditorTarget?
+ @State private var showDetail = false
+ @State private var backupMode: MemoryBackupMode?
@State private var confirmClear = false
var body: some View {
CardSection("Memory") {
- if facts.isEmpty {
- Text(loaded
- ? "Nothing yet. The bot remembers who you are and what you work on as you chat."
- : "Loading…")
- .foregroundStyle(Palette.secondary)
- }
- ForEach(facts) { fact in
- HStack(alignment: .firstTextBaseline, spacing: 10) {
- Image(systemName: fact.kind == "profile" ? "person" : "clock")
- .font(.caption)
- .foregroundStyle(Palette.tertiary)
- .help(fact.kind == "profile" ? "About you" : "History")
- Text(fact.content)
- .foregroundStyle(Palette.text)
- .frame(maxWidth: .infinity, alignment: .leading)
- Button("Forget", systemImage: "xmark") { forget(fact) }
- .labelStyle(.iconOnly)
- .buttonStyle(.plain)
- .font(.caption)
- .foregroundStyle(Palette.tertiary)
- .help("Forget")
- }
- }
+ if let memory { contents(memory) }
+ else { Text("Loading memory…").foregroundStyle(Palette.secondary) }
} accessory: {
- if !facts.isEmpty {
- Button("Forget everything", systemImage: "trash") { confirmClear = true }
- .labelStyle(.iconOnly)
- .buttonStyle(.plain)
- .foregroundStyle(Palette.secondary)
- .help("Forget everything")
- }
+ IconButton("Add memory", systemImage: "plus") { openEditor() }
+ .disabled(memory == nil || memory?.busy == true)
+ }
+ .task(id: botId) {
+ let store = MemoryStore(botId: botId) { try await host.ready() }
+ memory = store
+ await store.load()
+ }
+ .codyncSheet(item: $editor) { target in
+ if let memory { MemoryEditorView(memory: memory, draft: target.draft) }
+ }
+ .codyncSheet(isPresented: $showDetail) {
+ if let memory { MemoryHistoryView(memory: memory) }
+ }
+ .codyncSheet(item: $backupMode) { mode in
+ if let memory { MemoryBackupView(memory: memory, mode: mode) }
}
- .task(id: botId) { await load() }
.codyncDialog("Forget everything this bot remembers?", isPresented: $confirmClear) {
- [DialogAction("Forget everything", destructive: true) { clear() }]
+ [DialogAction("Forget everything", destructive: true) {
+ Task { await memory?.action("clearMemory") }
+ }]
}
}
- private func load() async {
- guard let client = model.client else { return }
- facts = (try? await client.memory(botId: botId).facts) ?? []
- loaded = true
- }
-
- private func forget(_ fact: MemoryFact) {
- withAnimation(Motion.layout) { facts.removeAll { $0.id == fact.id } }
- Task {
- try? await model.client?.forgetMemory(botId: botId, id: fact.id)
- await load()
+ @ViewBuilder private func contents(_ memory: MemoryStore) -> some View {
+ SearchField("Search memories", text: Binding(get: { memory.query }, set: { memory.search($0) }))
+ ScrollView(.horizontal) {
+ HStack(spacing: 14) {
+ ForEach(["all", "profile", "pinned", "review"], id: \.self) { filter in
+ Button(["all": "All", "profile": "About you", "pinned": "Pinned", "review": "Needs review"][filter] ?? filter) {
+ withAnimation(Motion.layout) { memory.search(memory.query, filter: filter) }
+ }
+ .fontWeight(memory.filter == filter ? .semibold : .regular)
+ .foregroundStyle(memory.filter == filter ? Palette.text : Palette.secondary)
+ }
+ }
+ .buttonStyle(.plain)
+ }
+ if let error = memory.error { Text(error).foregroundStyle(Palette.danger).textSelection(.enabled) }
+ if !memory.loaded && memory.error == nil { Text("Loading memory…").foregroundStyle(Palette.secondary) }
+ if memory.loaded && memory.facts.isEmpty {
+ Text(memory.query.isEmpty && memory.filter == "all"
+ ? "Nothing yet. Important details are remembered as you chat." : "No matching memories.")
+ .foregroundStyle(Palette.secondary)
+ }
+ ForEach(memory.facts) { fact in
+ VStack(alignment: .leading, spacing: 8) {
+ Button { openEditor(fact) } label: {
+ VStack(alignment: .leading, spacing: 4) {
+ Text((fact.pinned ? "● " : "") + fact.title).fontWeight(.semibold)
+ Text(fact.content).lineLimit(3)
+ Text("\(fact.kind == "profile" ? "About you" : fact.memoryType) · \(Date(timeIntervalSince1970: Double(fact.createdAt) / 1000).formatted(date: .abbreviated, time: .omitted)) · \(fact.revisionCount) revisions")
+ .font(.caption).foregroundStyle(Palette.secondary)
+ }
+ .frame(maxWidth: .infinity, alignment: .leading)
+ .contentShape(Rectangle())
+ }
+ .buttonStyle(.plain)
+ ScrollView(.horizontal) {
+ HStack(spacing: 14) {
+ Button(fact.pinned ? "Unpin" : "Pin") { Task { await memory.action("pinMemory", fact: fact) } }
+ Button("History") {
+ withAnimation(Motion.layout) { showDetail = true }
+ Task { await memory.inspect(fact) }
+ }
+ if fact.reviewAfter != nil {
+ Button("Mark reviewed") { Task { await memory.action("reviewMemory", fact: fact) } }
+ }
+ Button("Forget") { Task { await memory.action("forgetMemory", fact: fact) } }
+ }
+ .buttonStyle(.plain).font(.caption).foregroundStyle(Palette.secondary)
+ .disabled(memory.busy)
+ }
+ }
+ .padding(.vertical, 6)
+ }
+ if memory.nextOffset != nil {
+ Button("Load more (\(memory.total))") { Task { await memory.load(more: true) } }.buttonStyle(.plain)
+ }
+ ScrollView(.horizontal) {
+ HStack(spacing: 14) {
+ Button("Refresh") { Task { await memory.load() } }
+ Button("Export") {
+ withAnimation(Motion.layout) { backupMode = .export }
+ Task { await memory.export() }
+ }
+ Button("Import") { withAnimation(Motion.layout) { backupMode = .import } }
+ Button("Forget everything") { withAnimation(Motion.layout) { confirmClear = true } }
+ .disabled(memory.busy)
+ }
+ .buttonStyle(.plain).font(.caption).foregroundStyle(Palette.secondary)
}
}
- private func clear() {
- withAnimation(Motion.layout) { facts = [] }
- Task {
- try? await model.client?.clearMemory(botId: botId)
- await load()
- }
+ private func openEditor(_ fact: MemoryFact? = nil) {
+ withAnimation(Motion.layout) { editor = MemoryEditorTarget(draft: MemoryDraft(botId: botId, fact: fact)) }
}
}
+
+private struct MemoryEditorTarget: Identifiable {
+ let id = UUID()
+ var draft: MemoryDraft
+}
diff --git a/apps/ios/Kit/Sources/CodyncUI/Store/MemoryStore.swift b/apps/ios/Kit/Sources/CodyncUI/Store/MemoryStore.swift
new file mode 100644
index 00000000..9a3f8b24
--- /dev/null
+++ b/apps/ios/Kit/Sources/CodyncUI/Store/MemoryStore.swift
@@ -0,0 +1,104 @@
+import CodyncKit
+import Foundation
+import Observation
+
+@MainActor @Observable
+final class MemoryStore {
+ let botId: String
+ private let client: () async throws -> HostClient
+ var facts: [MemoryFact] = []
+ var query = ""
+ var filter = "all"
+ var total = 0
+ var nextOffset: Int?
+ var loaded = false
+ var busy = false
+ var error: String?
+ var detail: MemoryDetail?
+ var backup = ""
+ private var request = 0
+ private var detailRequest = 0
+ private var searchTask: Task<Void, Never>?
+
+ init(botId: String, client: @escaping () async throws -> HostClient) {
+ self.botId = botId
+ self.client = client
+ }
+
+ func load(more: Bool = false) async {
+ request += 1
+ let asked = request
+ guard let offset = more ? nextOffset : 0 else { return }
+ error = nil
+ do {
+ let listing = try await client().memory(botId: botId, query: query, filter: filter, offset: offset)
+ guard asked == request else { return }
+ facts = more ? facts + listing.facts : listing.facts
+ total = listing.total
+ nextOffset = listing.nextOffset
+ loaded = true
+ } catch {
+ if asked == request { self.error = error.localizedDescription }
+ }
+ }
+
+ func search(_ query: String, filter: String? = nil) {
+ self.query = query
+ if let filter { self.filter = filter }
+ request += 1
+ searchTask?.cancel()
+ searchTask = Task {
+ do { try await Task.sleep(for: .milliseconds(250)) } catch { return }
+ await load()
+ }
+ }
+
+ func action(_ method: String, fact: MemoryFact? = nil) async {
+ _ = await perform {
+ try await self.client().memoryAction(method, botId: self.botId, id: fact?.id, pinned: fact.map { !$0.pinned })
+ }
+ }
+
+ func save(_ draft: MemoryDraft) async -> Bool {
+ await perform { try await self.client().saveMemory(draft) }
+ }
+
+ func inspect(_ fact: MemoryFact, cursor: Int? = nil) async {
+ detailRequest += 1
+ let asked = detailRequest
+ error = nil
+ if cursor == nil { detail = nil }
+ do {
+ let value = try await client().memoryDetail(botId: botId, id: fact.id, cursor: cursor)
+ if asked == detailRequest { detail = value }
+ } catch {
+ if asked == detailRequest { self.error = error.localizedDescription }
+ }
+ }
+
+ func export() async {
+ backup = ""
+ error = nil
+ do { backup = try await client().exportMemory(botId: botId) }
+ catch { self.error = error.localizedDescription }
+ }
+
+ func importBackup(_ text: String) async -> Bool {
+ await perform { try await self.client().importMemory(botId: self.botId, json: text) }
+ }
+
+ private func perform(_ work: () async throws -> Void) async -> Bool {
+ guard !busy else { return false }
+ busy = true
+ error = nil
+ defer { busy = false }
+ do {
+ try await work()
+ await load()
+ return true
+ } catch {
+ self.error = error.localizedDescription
+ return false
+ }
+ }
+}
diff --git a/apps/ios/Kit/Tests/CodyncUITests/StoreTests.swift b/apps/ios/Kit/Tests/CodyncUITests/StoreTests.swift
index d5c49bad..ba9131c4 100644
--- a/apps/ios/Kit/Tests/CodyncUITests/StoreTests.swift
+++ b/apps/ios/Kit/Tests/CodyncUITests/StoreTests.swift
@@ -638,29 +638,29 @@ private func helloJSON(version: String, minApp: String? = nil, backends: String
defer { UserDefaults(suiteName: suite)?.removePersistentDomain(forName: suite) }
let fake = FakeRemote(.ready(.relay))
await fake.setHello(helloJSON(version: "2.2.0"))
- let store = BotStore(computer: randomComputer("Mac"), clientKind: "ios", storage: storage, appVersion: "2.4.0") { fake }
+ let store = BotStore(computer: randomComputer("Mac"), clientKind: "ios", storage: storage, appVersion: "2.12.0") { fake }
defer { store.retire() }
store.setActive(true)
#expect(await until { store.mismatch == .updateHost(version: "2.2.0", minimum: VersionMismatch.minHost) })
// The host updates and restarts: the link drops and comes back.
- await fake.setHello(helloJSON(version: "2.4.0", minApp: "2.3.0"))
+ await fake.setHello(helloJSON(version: "2.12.0", minApp: "2.3.0"))
await fake.set(.connecting)
await fake.set(.ready(.relay))
#expect(await until { store.mismatch == nil })
#expect(await until { await fake.subscribed })
- #expect(store.hostVersion == HostVersion(version: "2.4.0", minApp: "2.3.0"))
+ #expect(store.hostVersion == HostVersion(version: "2.12.0", minApp: "2.3.0"))
}
@MainActor @Test func unreadableHelloStillSaysWhichSideToUpdate() async throws {
let (storage, suite) = context()
defer { UserDefaults(suiteName: suite)?.removePersistentDomain(forName: suite) }
// A newer host whose hello this app can't decode, with or without a minApp that covers it.
- for minApp in ["2.6.0", "2.0.0"] {
+ for minApp in ["2.14.0", "2.0.0"] {
let fake = FakeRemote(.ready(.relay))
- await fake.setHello(helloJSON(version: "2.6.0", minApp: minApp, backends: #""changed shape""#))
- let store = BotStore(computer: randomComputer("Mac"), clientKind: "ios", storage: storage, appVersion: "2.4.0") { fake }
+ await fake.setHello(helloJSON(version: "2.14.0", minApp: minApp, backends: #""changed shape""#))
+ let store = BotStore(computer: randomComputer("Mac"), clientKind: "ios", storage: storage, appVersion: "2.12.0") { fake }
store.setActive(true)
- #expect(await until { store.mismatch == .updateApp(minimum: "2.6.0") }, "minApp \(minApp)")
+ #expect(await until { store.mismatch == .updateApp(minimum: "2.14.0") }, "minApp \(minApp)")
#expect(store.hello == nil)
store.retire()
}
@@ -669,10 +669,10 @@ private func helloJSON(version: String, minApp: String? = nil, backends: String
@MainActor @Test func unreadableEventsAskForAnAppUpdateOnlyFromANewerHost() async throws {
let (storage, suite) = context()
defer { UserDefaults(suiteName: suite)?.removePersistentDomain(forName: suite) }
- for (hostVersion, appIsBehind) in [("2.6.0", true), ("2.4.0", false)] {
+ for (hostVersion, appIsBehind) in [("2.14.0", true), ("2.12.0", false)] {
let fake = FakeRemote(.ready(.relay))
await fake.setHello(helloJSON(version: hostVersion, minApp: "2.3.0"))
- let store = BotStore(computer: randomComputer("Mac"), clientKind: "ios", storage: storage, appVersion: "2.4.0") { fake }
+ let store = BotStore(computer: randomComputer("Mac"), clientKind: "ios", storage: storage, appVersion: "2.12.0") { fake }
store.setActive(true)
let broken = #"{"type":"bot","bot":{"id":"b1","name":7}}"#
#expect(await until { await fake.eventSubscriptionCount == 1 })
diff --git a/docs/architecture/conversation-runtime.md b/docs/architecture/conversation-runtime.md
new file mode 100644
index 00000000..3f4b7869
--- /dev/null
+++ b/docs/architecture/conversation-runtime.md
@@ -0,0 +1,7 @@
+# Conversation runtime
+
+- **Chat ≠ session**: a bot is one endless transcript (SQLite `entries`, ordered by `seq`); the ACP session underneath is resumed with `session/load` or replaced by *New session*.
+- **Group chats and threads** are host features every client drives through the same methods (`send` with `threadId`, `thread`, `createBot {kind: group}`); clients never route, parse mentions or count replies themselves. A group is a roster row whose members answer in their own sessions (Grok Bot's room turns); a thread on a bot's message is a forked session: [docs/features/groups-and-threads.md](../features/groups-and-threads.md).
+- Bot collaboration: built-in `team` MCP (`chat/team.rs`) lists visible bots and asks one for a reply or sends it an independent message through its actor queue. Asks are separate turns, cycle-checked and cancellable; native subagents stay with the harness. See [docs/features/bot-collaboration.md](../features/bot-collaboration.md).
+- **Context & memory**: frozen instruction snapshot per session + compaction epoch (Claude gets it as a system prompt), profile edits as update blocks, per-bot Engram SQLite memory with a keeper agent, busy-time messages folded into one turn, interrupted turns resumed: [docs/features/context-and-memory.md](../features/context-and-memory.md).
+- **Chat shows only**: user messages, the bot's messages (`data.final`: each `send_message` call from the built-in `chat` MCP, Grok Bot's way; a turn that sent none falls back to its last text), permission cards, notices. Nothing streams into a bubble; narration, thoughts, tool calls, plans are trace entries (Full conversation sheet): [docs/features/chat-messages.md](../features/chat-messages.md).
diff --git a/docs/features/context-and-memory.md b/docs/features/context-and-memory.md
index d52b232c..fda738c2 100644
--- a/docs/features/context-and-memory.md
+++ b/docs/features/context-and-memory.md
@@ -1,8 +1,7 @@
# Context and memory
-How a bot keeps its instructions, context and long-term memory. The mechanisms follow Grok Bot's design
-(`system-prompt-assembly`, `sand-memory`, `turn-memory`, `upgrade-recreate-resume`) and are adapted to ACP,
-where the harness owns the conversation.
+How a bot keeps its instructions, context and long-term memory. Engram owns durable memory; Codync manages
+capture, recall and the keeper. The ACP harness owns the conversation and compaction.
## Transcript, context and memory
@@ -10,7 +9,7 @@ where the harness owns the conversation.
|---|---|---|---|
| Transcript | SQLite `entries` | Codync | Persistent main chat and flat reply threads per bot |
| Model context | ACP session (`bots.session_id`) | The harness | Until *New session*, a failed resume, or an agent/command/folder change |
-| Long-term memory | `~/.codync/bots/<id>/memory/` | Codync (keeper) + the user | Forever, across sessions |
+| Long-term memory | `~/.codync/bots/<id>/engram/engram.db` | Engram + Codync keeper + the user | Forever, across sessions |
Codync never replays the transcript into a session. Each turn sends only the new message(s); the harness keeps
its own context and compacts it itself.
@@ -35,34 +34,20 @@ its own context and compacts it itself.
## Memory (`host/src/chat/memory/`)
-- Facts are plain markdown, one `- (YYYY-MM-DD) fact` per line:
- - `profile.md` holds who the user is. All of it goes into the prompt, up to 100 facts. When it grows past
- 100, the keeper consolidates it to at most 60 (merging duplicates, dropping superseded facts); every fact it
- drops moves to the log, so nothing is lost.
- - `log/YYYY-MM.md` holds dated history, including `[note]` and `[episode]` lines. The newest 30 go into the
- prompt, within 4,000 characters.
-- **Keeper:** after a turn ends normally, if the user's message is memorable (not "thanks"/"ok"), the exchange
- is queued (`memory.unprocessed.<bot>`, so a restart keeps it). Once the bot has been quiet for 5 minutes, or 8
- exchanges are queued, a one-shot agent of the bot's own harness extracts facts from all of them at once using
- Grok Bot's extraction prompt (`profile:` / `log:` / `note:` / `remove:`). Running per exchange would buy
- nothing: the frozen prompt only picks up new facts at the next compaction or session.
- - On Claude it runs with a replaced system prompt, no tools, no settings, `persistSession: false` and the
- `haiku` model.
- - Other harnesses get the instructions inline, in `~/.codync/memory-keeper`.
-- **History search:** the built-in `memory` MCP server (`codync-host mcp memory`) gives the bot
- `search_history`, a substring search (every word must appear) over its own chat: the user's messages and its
- final replies, main chat and threads. Whatever the keeper didn't write down can still be found.
-- **Episodes:** every 6 remembered exchanges (pending turns in `memory.episode.<bot>`), the keeper writes one
- `[episode]` journal sentence.
-- **Automatic names** (`chat/naming.rs`): a bot created without a name is called "New Bot" with `autoName` set;
- clients don't ask for a name when creating one. From its 3rd remembered exchange the keeper shows the last 6
- (`naming.turns.<bot>`) to the same one-shot agent and asks for a 1–4 word name in the user's language, retrying
- after each exchange until the purpose is clear. The name goes through `updateBot`, so the agent gets it as a
- profile update. The description is never touched (it holds standing instructions). Renaming the bot yourself
- clears `autoName` for good.
-- The agent is told where its memory folder is so it can grep older facts. Facts learned mid-session reach its
- prompt at the next compaction or session.
-- **API:** `memory`, `forgetMemory`, `clearMemory`. The Memory card in bot settings lists and removes facts.
+- Engram stores each bot's durable observations in an independent SQLite database. The old Markdown memory
+ imports automatically, with original dates and source references preserved.
+- The instruction snapshot includes up to 100 profile facts and 30 recent facts, within a 4,000-character
+ recent-memory budget. A keeper consolidates crowded profiles to at most 60 facts; demoted facts remain
+ searchable. Manual corrections invalidate snapshots and send a notice on the next turn.
+- Completed memorable exchanges queue durably. After five idle minutes or eight exchanges, the bot's own
+ harness extracts durable facts and saves a native Engram session summary. A new session or reported
+ compaction requests an early flush. Failed batches remain queued for retry.
+- Claude's keeper uses Haiku without tools, settings or persisted helper sessions; other harnesses use the
+ bot's selected model with inline instructions. Automatic naming still uses `chat/naming.rs`.
+- The built-in memory MCP server forwards native Engram tools for recall, saving, review and conflict
+ judgment, and retains `search_history` for the bot's original main-chat and thread messages.
+- iOS, desktop and terminal provide search, CRUD, pinning, review, history, timeline, export and import.
+ See [Engram memory integration](engram-memory.md) for storage, migration, deletion semantics, API and tests.
## Turns
@@ -81,8 +66,8 @@ its own context and compacts it itself.
afterwards.
- A session a harness has deleted (for example, one cleaned up after a month) can't be resumed. The bot
starts fresh, but its memory remains.
-- User-level memory shared across bots and project memory are not implemented. Consolidation runs only when the
- profile outgrows the prompt, not as Grok Bot's daily "dreaming" pass.
+- Memory scopes stay inside a bot's database; user-level sharing across bots is not implemented. Search uses
+ FTS5 rather than semantic vectors. Consolidation runs when the profile outgrows the prompt, not daily.
- `search_history` covers the bot's own chat, not group chats it took part in.
Reply threads have separate session/context lanes; see [groups and threads](groups-and-threads.md). Group/delegated requests do not become user facts in the memory keeper.
diff --git a/docs/features/engram-memory.md b/docs/features/engram-memory.md
new file mode 100644
index 00000000..c37b5cc6
--- /dev/null
+++ b/docs/features/engram-memory.md
@@ -0,0 +1,117 @@
+# Engram memory integration
+
+Codync uses [Engram v3.2.1](https://github.com/Gentleman-Programming/engram/releases/tag/v3.2.1)
+for durable memory. Codync supplies chat capture, automatic extraction, prompt recall and management UI.
+ACP still owns the agent conversation and compaction; the built-in **memory MCP server** exposes Engram's
+native tools plus Codync's `search_history`. ACP and MCP have different responsibilities.
+
+## Storage and runtime
+
+Each bot has an independent `bots/<id>/engram/engram.db` under `CODYNC_HOME` (normally `~/.codync`).
+The host downloads the MIT-licensed release on first use, validates its SHA-256 against
+`packaging/engram/release.json`, and installs it with its license in `engram/3.2.1/`.
+First use requires network access; subsequent use works offline. Supported binaries are macOS, Linux and
+Windows, each on arm64 and x86_64. No global Engram install or HTTP listener is needed.
+
+The host lazily starts one native MCP stdio process per active bot. Requests serialize within that process;
+an idle process stops after five minutes and restarts on demand. A failed request is reported, never silently
+replayed: a write may have reached SQLite before its acknowledgement was lost. Inspect memory before retrying.
+Engram cloud autosync is disabled. Bot isolation is a separate database and tool routing, not a filesystem
+sandbox for an agent that already has shell access.
+
+Engram owns schema migrations and every database write. Codync reads the pinned schema in read-only mode
+for structured management, prompt facts and full FTS pagination. Upgrading the pin requires rerunning native
+integration tests and checking this schema contract. This is keyword/trigram FTS5 search, not vector similarity.
+Short one/two-character queries use escaped substring matching; longer terms use the existing FTS index.
+Native MCP search retains Engram's own result limits; the management screen paginates the entire result set.
+
+## Automatic migration
+
+On a bot's first memory access, `memory/profile.md` and `memory/log/*.md` are copied verbatim into an
+immutable `engram/markdown-backup.json` import journal. Each dated bullet receives a deterministic sync ID;
+its original date, content, profile/log scope and source path/line are imported through the native CLI.
+The host verifies every imported ID before writing `.codync-markdown-imported`. Interrupted imports retry
+without duplicating records. Malformed dated rows fail visibly instead of being silently discarded.
+The original Markdown remains untouched as a backup and is no longer authoritative.
+
+The completion marker is retained by **Forget everything** so old Markdown cannot reappear. Removing the
+marker is a deliberate recovery operation, not part of normal startup. To roll back to an older Codync build,
+stop the host first and retain both the Engram directory and original Markdown. The original files contain
+only pre-migration memory; newer Engram data must be exported separately and is not automatically converted
+back into the legacy format.
+
+## Management and automation
+
+Desktop, iOS and terminal expose search, filters (all/about you/pinned/due for review), paginated browsing,
+add/edit, scope/category/topic, pin/unpin, mark reviewed, observation history and session timeline, forget,
+clear, and JSON export/import. A `personal` or `global` scope remains within this bot's database; it does not
+share memories with other bots. The TUI shows operation shortcuts in the memory sheet footer.
+
+The main agent receives native Engram tools, including review, comparison and conflict judgment. Dedicated
+conflict adjudication screens are not implemented; those operations are available to the agent through MCP.
+The keeper remains responsible for automatically extracting durable facts from completed user conversations,
+consolidating a crowded profile, and saving native `session_summary` observations. It runs after five idle
+minutes or eight queued exchanges; new-session and compaction events request an early flush. Summaries are
+incremental batches of a session. The harness's compacted context is a separate artifact.
+
+Exchanges remain in the durable Codync queue until processing succeeds. Failures are logged and retried after
+five minutes. Explicit memory corrections invalidate prompt snapshots and pending old extraction work;
+in-progress extraction checks a revision before writing. Editing memory sends a correction notice on the
+next agent turn. It cannot remove text already held in a harness's context; start a new session when needed.
+The transcript is retained separately and is still searchable with `search_history`.
+
+**Forget** soft-deletes an observation through Engram. **Forget everything** invokes native hard project
+deletion for observations, captured prompts and sessions, discards pending keeper work, and invalidates prompt
+snapshots. Original transcripts, explicitly retained migration/import backups, and Engram audit metadata are
+not secure-erased. This action clears active memory, not every historical copy on disk.
+
+## Backups and API
+
+Export uses Engram's native direct-backup format, including observations, sessions, prompts, pins, relations
+and tombstones supported by that version. Import saves `before-import-<uuid>.json` first and merges using
+Engram sync IDs and timestamps. It preserves newer changes; importing an older backup is not guaranteed to
+undo a newer deletion. Cross-bot imports remap project/session ownership into the destination's database.
+Engram's JSON format does not include the separate observation revision-history table; old version contents
+are therefore not restored by a JSON import. For a complete local archive including that history, stop the
+host and back up the whole `engram/` directory. Backups larger than 384 KiB use Codync's existing chunked
+attachment transport; imports accept up to 100 MiB.
+Retained backups and transfer files are local files, so ordinary host backup/retention policies apply.
+
+Authenticated client methods: `memory`, `saveMemory`, `memoryDetail`, `pinMemory`, `reviewMemory`,
+`forgetMemory`, `clearMemory`, `exportMemory`, `importMemory`. The local-only MCP bridge uses `memoryTools`
+and `memoryCall`; agents receive their real ACP session binding, including independent thread sessions.
+
+## Verification
+
+`packaging/engram/test-runtime.py` downloads and checksum-verifies the same pinned binary used by the host.
+Set `CODYNC_TEST_ENGRAM` to its output path, then run:
+
+```sh
+cd host
+cargo fmt --check
+cargo clippy --all-targets -- -D warnings
+cargo test
+cargo test --test memory_e2e -- --ignored
+cargo test native_memory_survives_restart_and_cannot_read_another_bot -- --ignored
+```
+
+Host CI repeats the native tests on its platform matrix. The integration fixture always uses disposable data;
+it never migrates the developer's real bots.
+
+## Local validation (2.12.0)
+
+- Host: formatting and Clippy; 227 unit tests; 15 host, 10 routine and 4 team integration tests.
+- Native Engram: restart/isolation; Markdown migration, Chinese pagination, edits/history/pins, clear including
+ captured prompts, cross-bot import; large chunked backups; automatic extraction and native summaries on
+ new-session flush. Tests use deterministic ACP fixtures, not a paid model provider.
+- Desktop: TypeScript check, 87 tests and production build; browser interaction against a real disposable
+ host for add, pin, edit, Chinese search, history, export and clear.
+- Terminal: actual PTY interaction for memory browsing, adding and reading history. Footer shortcuts were
+ shortened after checking the standard-width sheet.
+- iOS: 111 package tests on an iOS 26.5 simulator, including the latest memory views and compatibility floor.
+ Physical-device memory UI and Linux/Windows runtime behavior were not exercised locally; the latter run
+ in the host CI matrix.
+
+The initial parallel host integration run hit one fixture startup timeout; all 29 host/routine/team
+integration cases passed with one test thread. Raising the client host floor exposed an older version in
+an unrelated iOS fake-host fixture; it now uses the current floor and the full suite passes.
diff --git a/host/src/agent/bot/mod.rs b/host/src/agent/bot/mod.rs
index fe096df7..cd5d8887 100644
--- a/host/src/agent/bot/mod.rs
+++ b/host/src/agent/bot/mod.rs
@@ -123,6 +123,8 @@ pub fn spawn(hub: Arc<Hub>, cfg: BotConfig) -> BotHandle {
applied_system: None,
keeper,
turn_text: None,
+ memory_session: None,
+ turn_memory_revision: String::new(),
announce: None,
turn: None,
queue: VecDeque::new(),
@@ -201,9 +203,11 @@ struct Actor {
session_fresh: bool,
/// (session, instructions) last handed to Claude as its system prompt by this process.
applied_system: Option<(String, String)>,
- keeper: mpsc::UnboundedSender<memory::Exchange>,
+ keeper: mpsc::UnboundedSender<memory::KeeperEvent>,
/// The user's words for this turn (None for a hidden turn); feeds memory.
turn_text: Option<String>,
+ memory_session: Option<String>,
+ turn_memory_revision: String,
/// A profile update this turn carried, recorded once the agent got it.
announce: Option<(Snapshot, Identity)>,
turn: Option<i64>,
diff --git a/host/src/agent/bot/queue.rs b/host/src/agent/bot/queue.rs
index 18a8c738..bf794c26 100644
--- a/host/src/agent/bot/queue.rs
+++ b/host/src/agent/bot/queue.rs
@@ -68,10 +68,8 @@ impl Actor {
self.stop().await;
}
self.forget_session();
- // Like Grok Bot's clearConversation: the half-written episode goes too; memory stays.
- if let Err(error) = memory::set_pending_episode(&self.hub.store, &self.cfg.id, &[]) {
- tracing::warn!(bot = %self.cfg.id, error = format!("{error:#}"), "couldn't clear the pending episode");
- }
+ // Retain and summarize completed exchanges even when the user starts afresh.
+ let _ = self.keeper.send(memory::KeeperEvent::Flush);
self.notice("New session — the agent starts with a fresh context.", NoticeStyle::Divider);
}
Cmd::Reconfigure(cfg) => {
diff --git a/host/src/agent/bot/session.rs b/host/src/agent/bot/session.rs
index 87e4d6d0..cc132679 100644
--- a/host/src/agent/bot/session.rs
+++ b/host/src/agent/bot/session.rs
@@ -116,10 +116,15 @@ impl Actor {
composio.then_some("composio"),
];
for name in builtin.into_iter().flatten() {
+ let env = if name == "memory" {
+ json!([{"name":"CODYNC_MEMORY_LANE", "value":self.slot(&self.lane).unwrap_or_default()}])
+ } else {
+ json!([])
+ };
servers.push(json!({
"name": name, "command": exe,
"args": ["mcp", name, "--bot", self.cfg.id, "--port", port.to_string()],
- "env": [],
+ "env": env,
}));
}
Ok(Value::Array(servers))
@@ -128,6 +133,7 @@ impl Actor {
/// Makes sure the agent runs and `slot`'s session (main, or a thread's) is live;
/// sets `turn_session`. A thread without one forks the main session when it can.
pub(super) async fn ensure_session(&mut self, slot: Option<&str>) -> Result<()> {
+ crate::chat::memory::prepare(&self.cfg.id).await?;
if !self.cfg.connectors.is_empty()
|| self.hub.store.kv_read(&format!("agent-env:{}", self.cfg.backend))?.is_some()
{
diff --git a/host/src/agent/bot/turn.rs b/host/src/agent/bot/turn.rs
index 3735ebc3..ccb9aff4 100644
--- a/host/src/agent/bot/turn.rs
+++ b/host/src/agent/bot/turn.rs
@@ -44,6 +44,7 @@ impl Actor {
self.lane = lane.clone();
self.turn = Some(turn);
self.turn_text = (!hidden).then(|| text.to_owned());
+ self.turn_memory_revision = memory::maintenance::revision(&self.hub.store, &self.cfg.id);
self.announce = None;
self.stop_requested = false;
self.hub.team.start_turn(&self.cfg.id, self.active_request.as_ref());
@@ -107,8 +108,16 @@ impl Actor {
}
let claude = self.conn.as_ref().is_some_and(|c| c.claude);
let sid = self.turn_session.clone().ok_or_else(|| anyhow!("no session"))?;
+ let memory_session = memory::lifecycle::begin(&self.hub, &self.cfg.id, &sid).await?;
+ self.memory_session = Some(memory_session.clone());
+ if !hidden && let Err(error) = memory::lifecycle::capture_prompt(&self.cfg.id, &memory_session, text).await {
+ tracing::warn!(bot = %self.cfg.id, %error, "memory prompt capture failed");
+ }
let snapshot = self.snapshot(&sid).await?;
let mut prompt = text.to_owned();
+ if let Some(notice) = memory::lifecycle::change_notice(&self.hub, &self.cfg.id, &sid) {
+ prompt = format!("{notice}\n\n{prompt}");
+ }
if let Some(intro) = self.thread_intro.take() {
prompt = format!("{intro}\n\n{prompt}");
}
@@ -135,6 +144,10 @@ impl Actor {
}
// Written before this returns, so a Stop right after is sent after the prompt.
let answer = acp.send("session/prompt", params).await?;
+ if let Err(error) = memory::lifecycle::mark_announced(&self.hub, &self.cfg.id, &sid, &self.turn_memory_revision)
+ {
+ tracing::warn!(%error, "could not acknowledge memory update notice");
+ }
let done_tx = done_tx.clone();
tokio::spawn(async move {
let _ = done_tx.send(answer.response().await);
@@ -254,7 +267,13 @@ impl Actor {
if let (Some(user), Some(agent), "end_turn") = (self.turn_text.take(), &final_text, stop_reason.as_str())
&& memory::is_memorable(&user)
{
- let _ = self.keeper.send(memory::Exchange { user, agent: agent.clone(), at: now_ms() });
+ let _ = self.keeper.send(memory::KeeperEvent::Exchange(memory::Exchange {
+ user,
+ agent: agent.clone(),
+ at: now_ms(),
+ session: self.memory_session.clone().unwrap_or_default(),
+ revision: self.turn_memory_revision.clone(),
+ }));
}
self.hub.set_runtime(&self.id(), |r| {
r.status = if failed { BotStatus::Error } else { BotStatus::Idle };
diff --git a/host/src/agent/bot/updates.rs b/host/src/agent/bot/updates.rs
index 88b05f5f..21e60df6 100644
--- a/host/src/agent/bot/updates.rs
+++ b/host/src/agent/bot/updates.rs
@@ -99,7 +99,10 @@ impl Actor {
let Some(sid) = &self.turn_session else { return };
let id = u["compactionId"].as_str().unwrap_or_default();
match context::bump_epoch(&self.hub.store, &self.cfg.id, sid, id) {
- Ok(true) => self.notice("Earlier context was summarized to make room.", NoticeStyle::Info),
+ Ok(true) => {
+ let _ = self.keeper.send(crate::chat::memory::KeeperEvent::Flush);
+ self.notice("Earlier context was summarized to make room.", NoticeStyle::Info);
+ }
Ok(false) => {}
Err(error) => {
tracing::warn!(bot = %self.cfg.id, error = format!("{error:#}"), "couldn't record the compaction");
diff --git a/host/src/agent/registry.rs b/host/src/agent/registry.rs
index e8f6cf3b..7b63181e 100644
--- a/host/src/agent/registry.rs
+++ b/host/src/agent/registry.rs
@@ -317,7 +317,7 @@ fn remove_other_versions(installed: &Path) {
}
/// Blocking: unpacks `archive` into `dir` and makes `cmd` executable.
-fn extract(archive: &Path, dir: &Path, cmd: &Path) -> Result<()> {
+pub(crate) fn extract(archive: &Path, dir: &Path, cmd: &Path) -> Result<()> {
let name = archive.file_name().map(|n| n.to_string_lossy().to_lowercase()).unwrap_or_default();
// Multi-part extensions (`.tar.gz`) rule out `Path::extension`; `name` is already lowercased.
#[allow(clippy::case_sensitive_file_extension_comparisons)]
diff --git a/host/src/api/bots.rs b/host/src/api/bots.rs
index 169ab3ff..9d61ed75 100644
--- a/host/src/api/bots.rs
+++ b/host/src/api/bots.rs
@@ -39,8 +39,17 @@ pub(super) async fn call(hub: &Arc<Hub>, method: &str, b: Value) -> Result<Contr
)?,
"routineCall" => crate::routines::call(hub, str_arg(&b, "botId")?, str_arg(&b, "name")?, &b["arguments"])?,
"memoryCall" => {
- crate::chat::memory::call(hub, str_arg(&b, "botId")?, str_arg(&b, "name")?, &b["arguments"]).await?
+ let bot = str_arg(&b, "botId")?;
+ let name = str_arg(&b, "name")?;
+ let args = if name.starts_with("mem_") {
+ crate::chat::memory::lifecycle::bound_args(hub, bot, b["memoryLane"].as_str(), name, &b["arguments"])
+ .await?
+ } else {
+ b["arguments"].clone()
+ };
+ crate::chat::memory::call(hub, bot, name, &args).await?
}
+ "memoryTools" => crate::chat::memory::available_tools(hub, str_arg(&b, "botId")?).await?,
"chatCall" => {
crate::chat::outbox::call(hub, str_arg(&b, "botId")?, str_arg(&b, "name")?, &b["arguments"]).await?
}
@@ -206,22 +215,8 @@ pub(super) async fn call(hub: &Arc<Hub>, method: &str, b: Value) -> Result<Contr
hub.send_cmd(str_arg(&b, "botId")?, Cmd::NewSession)?;
json!({})
}
- "memory" => {
- let bot = str_arg(&b, "botId")?.to_owned();
- tokio::task::spawn_blocking(move || crate::chat::memory::describe(&bot)).await??
- }
- "forgetMemory" => {
- let bot = str_arg(&b, "botId")?.to_owned();
- let id = str_arg(&b, "id")?.to_owned();
- let removed =
- tokio::task::spawn_blocking(move || crate::chat::memory::Memory::for_bot(&bot)?.remove(&id)).await??;
- json!({"removed": removed})
- }
- "clearMemory" => {
- let bot = str_arg(&b, "botId")?.to_owned();
- tokio::task::spawn_blocking(move || crate::chat::memory::Memory::for_bot(&bot)?.clear()).await??;
- json!({})
- }
+ "memory" | "saveMemory" | "memoryDetail" | "pinMemory" | "reviewMemory" | "forgetMemory" | "clearMemory"
+ | "exportMemory" | "importMemory" => crate::chat::memory::manage::call(hub, method, &b).await?,
"react" => {
let e = hub.react(str_arg(&b, "entryId")?, str_arg(&b, "emoji")?)?;
json!({"entry": e})
diff --git a/host/src/chat/context.rs b/host/src/chat/context.rs
index 7a459d20..c6360ec1 100644
--- a/host/src/chat/context.rs
+++ b/host/src/chat/context.rs
@@ -147,9 +147,9 @@ pub fn render(store: &Store, cfg: &BotConfig) -> String {
lines.push(skills);
}
let mut out = lines.join("\n");
- match Memory::for_bot(&cfg.id) {
- Ok(mem) => {
- let (section, _) = memory::render(&mem.recall(memory::RECENT_PROMPT_LIMIT), mem.location());
+ match Memory::for_bot(&cfg.id).and_then(|mem| Ok((mem.recall(memory::RECENT_PROMPT_LIMIT)?, mem))) {
+ Ok((recall, mem)) => {
+ let (section, _) = memory::render(&recall, mem.location());
out.push_str("\n\n");
out.push_str(&section);
}
diff --git a/host/src/chat/memory/dates.rs b/host/src/chat/memory/dates.rs
new file mode 100644
index 00000000..1c0af333
--- /dev/null
+++ b/host/src/chat/memory/dates.rs
@@ -0,0 +1,14 @@
+//! UTC dates used by stored memories and transcript search.
+
+pub fn ymd(ms: i64) -> String {
+ if ms <= 0 {
+ return "unknown date".into();
+ }
+ chrono::DateTime::from_timestamp_millis(ms)
+ .map_or_else(|| "unknown date".into(), |date| date.format("%Y-%m-%d").to_string())
+}
+
+#[cfg(test)]
+pub(super) fn parse_ymd(raw: &str) -> Option<i64> {
+ Some(chrono::NaiveDate::parse_from_str(raw, "%Y-%m-%d").ok()?.and_hms_opt(0, 0, 0)?.and_utc().timestamp_millis())
+}
diff --git a/host/src/chat/memory/engram/backup.rs b/host/src/chat/memory/engram/backup.rs
new file mode 100644
index 00000000..01e8a7bc
--- /dev/null
+++ b/host/src/chat/memory/engram/backup.rs
@@ -0,0 +1,104 @@
+//! Native JSON backup/restore; no application-written SQLite rows.
+
+use super::{directory, install};
+use anyhow::{Context, Result, ensure};
+use serde_json::Value;
+use std::{path::Path, time::Duration};
+
+pub(in crate::chat::memory) async fn export(bot: &str) -> Result<Value> {
+ super::prepare(bot).await?;
+ let dir = directory(bot)?;
+ let file = dir.join(format!("export-{}.json", uuid::Uuid::new_v4()));
+ let result = async {
+ command(bot, "export", &file).await?;
+ Ok(serde_json::from_slice(&tokio::fs::read(&file).await?)?)
+ }
+ .await;
+ cleanup(&file).await;
+ result
+}
+
+pub(in crate::chat::memory) async fn import(bot: &str, data: &Value) -> Result<Value> {
+ ensure!(data["sessions"].is_array() && data["observations"].is_array(), "invalid Engram backup");
+ let data = scoped_backup(bot, data)?;
+ let bytes = serde_json::to_vec(&data)?;
+ ensure!(bytes.len() <= 100 * 1024 * 1024, "memory backup exceeds 100 MB");
+ let before = export(bot).await?;
+ let dir = directory(bot)?;
+ let backup = dir.join(format!("before-import-{}.json", uuid::Uuid::new_v4()));
+ tokio::fs::write(&backup, serde_json::to_vec(&before)?).await?;
+ let file = dir.join(format!("import-{}.json", uuid::Uuid::new_v4()));
+ tokio::fs::write(&file, bytes).await?;
+ let result = command(bot, "import", &file).await;
+ cleanup(&file).await;
+ result?;
+ Ok(serde_json::json!({"backup":backup}))
+}
+
+fn scoped_backup(bot: &str, data: &Value) -> Result<Value> {
+ let project = super::project(bot);
+ let mut data = data.clone();
+ let mut sessions = std::collections::HashMap::new();
+ for session in data["sessions"].as_array_mut().context("backup has no sessions")? {
+ let old = session["id"].as_str().context("backup session has no id")?.to_owned();
+ let new = if session["project"] == project {
+ old.clone()
+ } else {
+ format!("{project}:import:{}", crate::chat::memory::read::content_hash(&old))
+ };
+ if new != old {
+ session["directory"] = "".into();
+ }
+ session["id"] = new.clone().into();
+ session["project"] = project.clone().into();
+ sessions.insert(old, new);
+ }
+ for collection in ["observations", "prompts", "prompt_tombstones"] {
+ for record in data[collection].as_array_mut().into_iter().flatten() {
+ if let Some(original) = record["project"].as_str().filter(|p| *p != project)
+ && collection == "observations"
+ {
+ record["tool_name"] =
+ format!("Imported from {original}; {}", record["tool_name"].as_str().unwrap_or_default()).into();
+ }
+ record["project"] = project.clone().into();
+ let source = record["session_id"].as_str().context("backup record has no session")?;
+ record["session_id"] = sessions.get(source).context("backup references an unknown session")?.clone().into();
+ }
+ }
+ for relation in data["relations"].as_array_mut().into_iter().flatten() {
+ if let Some(source) = relation["session_id"].as_str() {
+ relation["session_id"] =
+ sessions.get(source).context("relation references an unknown session")?.clone().into();
+ }
+ }
+ Ok(data)
+}
+
+async fn command(bot: &str, action: &str, file: &Path) -> Result<()> {
+ let mut command = tokio::process::Command::new(install::binary().await?);
+ command.arg(action).arg(file);
+ if action == "export" {
+ command.arg("--all");
+ }
+ let output = tokio::time::timeout(
+ Duration::from_secs(120),
+ command
+ .env("ENGRAM_DATA_DIR", directory(bot)?)
+ .env("ENGRAM_CLOUD_AUTOSYNC", "0")
+ .current_dir(directory(bot)?)
+ .kill_on_drop(true)
+ .output(),
+ )
+ .await??;
+ ensure!(output.status.success(), "Engram {action} failed: {}", String::from_utf8_lossy(&output.stderr));
+ Ok(())
+}
+
+async fn cleanup(file: &Path) {
+ if let Err(error) = tokio::fs::remove_file(file).await
+ && error.kind() != std::io::ErrorKind::NotFound
+ {
+ tracing::warn!(%error, path = %file.display(), "removing temporary memory backup failed");
+ }
+}
diff --git a/host/src/chat/memory/engram/clear.rs b/host/src/chat/memory/engram/clear.rs
new file mode 100644
index 00000000..b1f98ea4
--- /dev/null
+++ b/host/src/chat/memory/engram/clear.rs
@@ -0,0 +1,39 @@
+//! Clear observations, captured prompts and session summaries through the native CLI.
+
+use anyhow::{Result, ensure};
+use rusqlite::{Connection, OpenFlags};
+use std::time::Duration;
+
+pub(super) async fn run(bot: &str) -> Result<()> {
+ let dir = super::directory(bot)?;
+ let path = dir.join("engram.db");
+ let projects = tokio::task::spawn_blocking(move || -> Result<Vec<String>> {
+ let db = Connection::open_with_flags(path, OpenFlags::SQLITE_OPEN_READ_ONLY)?;
+ let mut query = db.prepare("SELECT project FROM sessions UNION SELECT project FROM observations")?;
+ Ok(query
+ .query_map([], |row| row.get::<_, Option<String>>(0))?
+ .collect::<rusqlite::Result<Vec<_>>>()?
+ .into_iter()
+ .flatten()
+ .filter(|s| !s.is_empty())
+ .collect())
+ })
+ .await??;
+ let binary = super::install::binary().await?;
+ for project in projects {
+ let result = tokio::time::timeout(
+ Duration::from_secs(120),
+ tokio::process::Command::new(&binary)
+ .args(["delete", "project", &project, "--hard"])
+ .env("ENGRAM_DATA_DIR", &dir)
+ .env("ENGRAM_CLOUD_AUTOSYNC", "0")
+ .current_dir(&dir)
+ .kill_on_drop(true)
+ .output(),
+ )
+ .await??;
+ ensure!(result.status.success(), "clearing Engram memory failed: {}", String::from_utf8_lossy(&result.stderr));
+ }
+ // The migration journal and completion marker remain: old Markdown must not be imported again.
+ Ok(())
+}
diff --git a/host/src/chat/memory/engram/install.rs b/host/src/chat/memory/engram/install.rs
new file mode 100644
index 00000000..9d45765f
--- /dev/null
+++ b/host/src/chat/memory/engram/install.rs
@@ -0,0 +1,114 @@
+//! Install one checksum-pinned binary, shared by every bot on this host.
+
+use super::VERSION;
+use anyhow::{Context, Result, bail, ensure};
+use sha2::{Digest, Sha256};
+use std::{fmt::Write as _, path::PathBuf, time::Duration};
+
+const RELEASES: &str = "https://github.com/Gentleman-Programming/engram/releases/download";
+const MAX_ARCHIVE_BYTES: usize = 128 * 1024 * 1024;
+static INSTALL: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
+
+pub(super) async fn binary() -> Result<PathBuf> {
+ #[cfg(test)]
+ if let Some(binary) = std::env::var_os("CODYNC_TEST_ENGRAM") {
+ return Ok(binary.into());
+ }
+ let _guard = INSTALL.lock().await;
+ let root = crate::service::data_dir().join("engram").join(VERSION);
+ let name = if cfg!(windows) { "engram.exe" } else { "engram" };
+ let binary = root.join(name);
+ if tokio::fs::try_exists(root.join(".installed")).await? && tokio::fs::try_exists(&binary).await? {
+ return Ok(binary);
+ }
+ let (platform, checksum) = distribution(std::env::consts::OS, std::env::consts::ARCH)?;
+ let extension = if cfg!(windows) { "zip" } else { "tar.gz" };
+ let archive = format!("engram_{VERSION}_{platform}.{extension}");
+ let mut response = crate::http()
+ .get(format!("{RELEASES}/v{VERSION}/{archive}"))
+ .timeout(Duration::from_secs(180))
+ .send()
+ .await?
+ .error_for_status()?;
+ let mut bytes = Vec::new();
+ while let Some(chunk) = response.chunk().await? {
+ ensure!(bytes.len() + chunk.len() <= MAX_ARCHIVE_BYTES, "Engram download exceeds size limit");
+ bytes.extend_from_slice(&chunk);
+ }
+ verify(&bytes, &checksum)?;
+ let staging = root.with_extension(format!("staging-{}", uuid::Uuid::new_v4()));
+ let (target, stage, executable) = (root.clone(), staging.clone(), name.to_owned());
+ let result = tokio::task::spawn_blocking(move || -> Result<()> {
+ std::fs::create_dir_all(&stage)?;
+ let file = stage.join(&archive);
+ std::fs::write(&file, bytes)?;
+ crate::agent::registry::extract(&file, &stage, std::path::Path::new(&executable))?;
+ let output = std::process::Command::new(stage.join(&executable)).arg("version").output()?;
+ ensure!(output.status.success(), "Engram version check failed");
+ let version = String::from_utf8(output.stdout)?;
+ ensure!(
+ version.split_whitespace().any(|v| v.trim_start_matches('v') == VERSION),
+ "unexpected Engram version: {version}"
+ );
+ std::fs::write(stage.join(".installed"), VERSION)?;
+ // A previous incomplete installation has never been used by a process.
+ if target.exists() {
+ std::fs::remove_dir_all(&target)?;
+ }
+ std::fs::rename(&stage, &target)?;
+ Ok(())
+ })
+ .await?;
+ if result.is_err()
+ && let Err(error) = tokio::fs::remove_dir_all(&staging).await
+ {
+ tracing::warn!(%error, "could not remove incomplete Engram installation");
+ }
+ result.context("installing Engram")?;
+ Ok(binary)
+}
+
+fn verify(bytes: &[u8], expected: &str) -> Result<()> {
+ let mut hash = String::with_capacity(64);
+ for byte in Sha256::digest(bytes) {
+ let _ = write!(hash, "{byte:02x}");
+ }
+ ensure!(hash == expected, "Engram download checksum mismatch");
+ Ok(())
+}
+
+fn distribution(os: &str, arch: &str) -> Result<(String, String)> {
+ let os = match os {
+ "macos" => "darwin",
+ "linux" => "linux",
+ "windows" => "windows",
+ _ => bail!("Engram does not support {os}"),
+ };
+ let arch = match arch {
+ "x86_64" => "amd64",
+ "aarch64" => "arm64",
+ _ => bail!("Engram does not support {arch}"),
+ };
+ let target = format!("{os}_{arch}");
+ let release: serde_json::Value =
+ serde_json::from_str(include_str!("../../../../../packaging/engram/release.json"))?;
+ ensure!(release["version"] == VERSION, "Engram release manifest version mismatch");
+ let checksum = release["assets"][&target].as_str().context("missing Engram release checksum")?.to_owned();
+ Ok((target, checksum))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn rejects_corrupt_release_and_unsupported_platform() {
+ assert!(verify(b"corrupt", &distribution("macos", "aarch64").unwrap().1).is_err());
+ assert!(distribution("linux", "riscv64").is_err());
+ for os in ["macos", "linux", "windows"] {
+ for arch in ["x86_64", "aarch64"] {
+ assert_eq!(distribution(os, arch).unwrap().1.len(), 64);
+ }
+ }
+ }
+}
diff --git a/host/src/chat/memory/engram/migrate.rs b/host/src/chat/memory/engram/migrate.rs
new file mode 100644
index 00000000..cdb493d9
--- /dev/null
+++ b/host/src/chat/memory/engram/migrate.rs
@@ -0,0 +1,161 @@
+//! One-way, retry-safe import of Codync's Markdown memory through Engram's native importer.
+
+use anyhow::{Context, Result, ensure};
+use serde_json::{Value, json};
+use sha2::{Digest, Sha256};
+use std::{collections::BTreeMap, fmt::Write as _, path::Path, time::Duration};
+
+const MARKER: &str = ".codync-markdown-imported";
+const BACKUP: &str = "markdown-backup.json";
+
+pub(super) async fn run(binary: &Path, dir: &Path, project: &str) -> Result<()> {
+ if tokio::fs::try_exists(dir.join(MARKER)).await? {
+ return Ok(());
+ }
+ tokio::fs::create_dir_all(dir).await?;
+ let backup = dir.join(BACKUP);
+ // The immutable backup is also the import journal. A retry always reads the same input,
+ // even when the old Markdown was edited after an interrupted migration.
+ if !tokio::fs::try_exists(&backup).await? {
+ let legacy = dir.parent().context("memory directory has no parent")?.join("memory");
+ let files = tokio::task::spawn_blocking(move || read_legacy(&legacy)).await??;
+ let staging = backup.with_extension("tmp");
+ tokio::fs::write(&staging, serde_json::to_vec_pretty(&files)?).await?;
+ tokio::fs::rename(&staging, &backup).await?;
+ }
+ let files: BTreeMap<String, String> = serde_json::from_slice(&tokio::fs::read(&backup).await?)?;
+ let payload = bundle(project, &files)?;
+ let count = payload["observations"].as_array().map_or(0, Vec::len);
+ if count > 0 {
+ let input = dir.join("markdown-import.json");
+ tokio::fs::write(&input, serde_json::to_vec(&payload)?).await?;
+ let output = tokio::time::timeout(
+ Duration::from_secs(180),
+ tokio::process::Command::new(binary)
+ .arg("import")
+ .arg(&input)
+ .env("ENGRAM_DATA_DIR", dir)
+ .env("ENGRAM_CLOUD_AUTOSYNC", "0")
+ .current_dir(dir)
+ .kill_on_drop(true)
+ .output(),
+ )
+ .await??;
+ ensure!(output.status.success(), "Engram memory import failed: {}", String::from_utf8_lossy(&output.stderr));
+ let database = dir.join("engram.db");
+ let expected: Vec<String> = payload["observations"]
+ .as_array()
+ .into_iter()
+ .flatten()
+ .filter_map(|v| v["sync_id"].as_str().map(str::to_owned))
+ .collect();
+ tokio::task::spawn_blocking(move || -> Result<()> {
+ let db = rusqlite::Connection::open_with_flags(database, rusqlite::OpenFlags::SQLITE_OPEN_READ_ONLY)?;
+ for id in expected {
+ let found: bool =
+ db.query_row("SELECT EXISTS(SELECT 1 FROM observations WHERE sync_id = ?)", [&id], |r| r.get(0))?;
+ ensure!(found, "Engram import omitted a memory: {id}");
+ }
+ Ok(())
+ })
+ .await??;
+ tokio::fs::remove_file(input).await?;
+ }
+ // This marker stays even after Forget everything: old files must never resurrect facts.
+ tokio::fs::write(dir.join(MARKER), format!("Engram {}: {count} memories\n", super::VERSION)).await?;
+ Ok(())
+}
+
+fn read_legacy(dir: &Path) -> Result<BTreeMap<String, String>> {
+ let mut files = BTreeMap::new();
+ match std::fs::read_to_string(dir.join("profile.md")) {
+ Ok(text) => {
+ files.insert("profile.md".into(), text);
+ }
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+ Err(e) => return Err(e).context("reading profile memory"),
+ }
+ match std::fs::read_dir(dir.join("log")) {
+ Ok(entries) => {
+ for entry in entries {
+ let path = entry?.path();
+ if path.extension().is_some_and(|x| x == "md") {
+ let name = path
+ .file_name()
+ .context("memory log has no filename")?
+ .to_str()
+ .context("memory log filename is not UTF-8")?;
+ files.insert(format!("log/{name}"), std::fs::read_to_string(&path)?);
+ }
+ }
+ }
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+ Err(e) => return Err(e).context("reading memory logs"),
+ }
+ Ok(files)
+}
+
+fn bundle(project: &str, files: &BTreeMap<String, String>) -> Result<Value> {
+ let session = format!("{project}:markdown-import");
+ let mut observations = Vec::new();
+ for (path, text) in files {
+ for (line, raw) in text.lines().enumerate() {
+ let Some(rest) = raw.trim().strip_prefix("- (") else {
+ continue;
+ };
+ let (date, content) = rest.split_once(") ").context("malformed dated memory; fix it before importing")?;
+ let date = chrono::NaiveDate::parse_from_str(date, "%Y-%m-%d").context("invalid date in memory")?;
+ ensure!(!content.trim().is_empty(), "empty memory in {path}:{}", line + 1);
+ let timestamp = format!("{date} 00:00:00");
+ let profile = path == "profile.md";
+ let source = format!("{project}\n{path}\n{}\n{raw}", line + 1);
+ let mut id = String::from("obs-codync-");
+ for b in Sha256::digest(source.as_bytes()) {
+ let _ = write!(id, "{b:02x}");
+ }
+ observations.push(json!({
+ "sync_id": id, "session_id": session, "project": project,
+ "type": if profile { "learning" } else { "discovery" },
+ "title": content.chars().take(100).collect::<String>(), "content": content,
+ "scope": if profile { "personal" } else { "project" },
+ "topic_key": format!("codync/import/{}/{}", path, line + 1),
+ "tool_name": format!("codync-import:{path}:{}", line + 1),
+ "created_at": timestamp, "updated_at": timestamp, "revision_count": 1,
+ }));
+ }
+ }
+ let start = observations.first().and_then(|o| o["created_at"].as_str()).unwrap_or("1970-01-01 00:00:00");
+ Ok(json!({
+ "version": "0.2.0", "exported_at": chrono::Utc::now().format("%Y-%m-%d %H:%M:%S").to_string(),
+ "sessions": [{"id": session, "project": project, "directory": "", "started_at": start,
+ "ended_at": start, "summary": "Imported Codync Markdown memory; original files preserved in markdown-backup.json"}],
+ "observations": observations, "prompts": [],
+ }))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn preserves_dates_sources_and_repeatable_import_identity() {
+ let files = BTreeMap::from([
+ ("profile.md".into(), "# Profile\n- (2026-01-01) 喜歡繁體中文\n".into()),
+ ("log/2026-02.md".into(), "- (2026-02-02) 發布 Codync\n".into()),
+ ]);
+ let a = bundle("bot-a", &files).unwrap();
+ let b = bundle("bot-a", &files).unwrap();
+ assert_eq!(a["observations"], b["observations"]);
+ let profile = &a["observations"][1];
+ assert_eq!(profile["created_at"], "2026-01-01 00:00:00");
+ assert_eq!(profile["content"], "喜歡繁體中文");
+ assert_eq!(profile["tool_name"], "codync-import:profile.md:2");
+ assert_ne!(profile["sync_id"], bundle("bot-b", &files).unwrap()["observations"][1]["sync_id"]);
+ }
+
+ #[test]
+ fn malformed_dated_fact_stops_import_instead_of_disappearing() {
+ let files = BTreeMap::from([("profile.md".into(), "- (2026-02-31) fact".into())]);
+ assert!(bundle("bot", &files).is_err());
+ }
+}
diff --git a/host/src/chat/memory/engram/mod.rs b/host/src/chat/memory/engram/mod.rs
new file mode 100644
index 00000000..1d7ec94d
--- /dev/null
+++ b/host/src/chat/memory/engram/mod.rs
@@ -0,0 +1,38 @@
+//! Pinned Engram runtime. Each bot owns a separate database and stdio process.
+//! Engram owns schema migrations and every write; Codync never writes its tables.
+
+mod backup;
+mod clear;
+mod install;
+mod migrate;
+mod process;
+
+use anyhow::{Result, bail};
+use std::path::PathBuf;
+
+pub(super) use backup::{export, import};
+pub(super) use process::{call, clear, prepare, tools};
+
+pub const VERSION: &str = "3.2.1";
+
+pub fn directory(bot_id: &str) -> Result<PathBuf> {
+ if bot_id.is_empty() || !bot_id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-') {
+ bail!("invalid bot id");
+ }
+ #[cfg(not(test))]
+ let root = crate::service::data_dir();
+ // Unit fixtures run several hosts with the same synthetic bot IDs on separate runtimes.
+ // Keep their real native databases isolated from each other and from the user's bots.
+ #[cfg(test)]
+ let root = {
+ static ROOT: std::sync::LazyLock<PathBuf> = std::sync::LazyLock::new(|| {
+ std::env::temp_dir().join(format!("codync-memory-unit-{}", uuid::Uuid::new_v4()))
+ });
+ ROOT.join(tokio::runtime::Handle::try_current()?.id().to_string())
+ };
+ Ok(root.join("bots").join(bot_id).join("engram"))
+}
+
+pub fn project(bot_id: &str) -> String {
+ format!("codync-{bot_id}")
+}
diff --git a/host/src/chat/memory/engram/process.rs b/host/src/chat/memory/engram/process.rs
new file mode 100644
index 00000000..61319d7a
--- /dev/null
+++ b/host/src/chat/memory/engram/process.rs
@@ -0,0 +1,230 @@
+//! Serialize native MCP requests per bot. A failed write is never replayed automatically.
+
+use super::{directory, install, project};
+use anyhow::{Context, Result, anyhow, bail, ensure};
+use serde_json::{Value, json};
+use std::{
+ collections::HashMap,
+ path::Path,
+ process::Stdio,
+ sync::{Arc, LazyLock, Once},
+ time::{Duration, Instant},
+};
+use tokio::{
+ io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader},
+ process::{Child, ChildStdin, ChildStdout},
+ sync::Mutex,
+};
+
+type Slot = Arc<Mutex<Option<Process>>>;
+static PROCESSES: LazyLock<Mutex<HashMap<String, Slot>>> = LazyLock::new(|| Mutex::new(HashMap::new()));
+const REQUEST_TIMEOUT: Duration = Duration::from_secs(90);
+const MAX_MESSAGE_BYTES: u64 = 8 * 1024 * 1024;
+
+struct Process {
+ child: Child,
+ input: ChildStdin,
+ output: BufReader<ChildStdout>,
+ last_used: Instant,
+ next_id: u64,
+}
+
+impl Process {
+ async fn start(binary: &Path, dir: &Path, project: &str) -> Result<Self> {
+ tokio::fs::create_dir_all(dir).await?;
+ let config_dir = dir.join(".engram");
+ tokio::fs::create_dir_all(&config_dir).await?;
+ let config = config_dir.join("config.json");
+ if tokio::fs::try_exists(&config).await? {
+ let saved: Value = serde_json::from_slice(&tokio::fs::read(&config).await?)?;
+ ensure!(saved["project_name"] == project, "Engram project binding does not match this bot");
+ } else {
+ tokio::fs::write(&config, serde_json::to_vec(&json!({"project_name":project}))?).await?;
+ }
+ let mut child = tokio::process::Command::new(binary)
+ .args(["mcp", "--project", project])
+ .env("ENGRAM_DATA_DIR", dir)
+ // Memory stays local even if the user's shell opts another Engram into cloud sync.
+ .env("ENGRAM_CLOUD_AUTOSYNC", "0")
+ .current_dir(dir)
+ .stdin(Stdio::piped())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::null())
+ .kill_on_drop(true)
+ .spawn()
+ .context("starting Engram")?;
+ let input = child.stdin.take().context("Engram stdin unavailable")?;
+ let output = BufReader::new(child.stdout.take().context("Engram stdout unavailable")?);
+ let mut process = Self { child, input, output, next_id: 0, last_used: Instant::now() };
+ process
+ .request(
+ "initialize",
+ json!({
+ "protocolVersion": crate::mcp::PROTOCOL_VERSION,
+ "capabilities": {},
+ "clientInfo": {"name": "codync", "version": env!("CARGO_PKG_VERSION")},
+ }),
+ )
+ .await?;
+ process.send(&json!({"jsonrpc":"2.0", "method":"notifications/initialized"})).await?;
+ let registered = process
+ .request(
+ "tools/call",
+ json!({"name":"mem_session_start", "arguments":{
+ "id": format!("{project}:codync-background"), "directory": dir,
+ }}),
+ )
+ .await?;
+ ensure!(registered["isError"] != true, "Engram session registration failed: {registered}");
+ Ok(process)
+ }
+
+ async fn send(&mut self, value: &Value) -> Result<()> {
+ let mut bytes = serde_json::to_vec(value)?;
+ bytes.push(b'\n');
+ self.input.write_all(&bytes).await?;
+ self.input.flush().await?;
+ Ok(())
+ }
+
+ async fn request(&mut self, method: &str, params: Value) -> Result<Value> {
+ self.next_id += 1;
+ let id = self.next_id;
+ self.send(&json!({"jsonrpc":"2.0", "id":id, "method":method, "params":params})).await?;
+ loop {
+ let mut line = Vec::new();
+ let read = (&mut self.output).take(MAX_MESSAGE_BYTES + 1).read_until(b'\n', &mut line).await?;
+ ensure!(read > 0, "Engram closed its output");
+ ensure!(read as u64 <= MAX_MESSAGE_BYTES, "Engram response exceeds size limit");
+ let value: Value = serde_json::from_slice(&line).context("invalid Engram response")?;
+ if value.get("id") != Some(&json!(id)) {
+ continue;
+ }
+ if let Some(error) = value.get("error") {
+ bail!("Engram: {error}");
+ }
+ return value.get("result").cloned().context("Engram response has no result");
+ }
+ }
+}
+
+fn start_idle_cleanup() {
+ static START: Once = Once::new();
+ START.call_once(|| {
+ tokio::spawn(async {
+ loop {
+ tokio::time::sleep(Duration::from_secs(60)).await;
+ let slots: Vec<Slot> = PROCESSES.lock().await.values().cloned().collect();
+ for slot in slots {
+ if let Ok(mut process) = slot.try_lock()
+ && process.as_ref().is_some_and(|p| p.last_used.elapsed() >= Duration::from_secs(300))
+ {
+ *process = None;
+ }
+ }
+ }
+ });
+ });
+}
+
+async fn request(bot: &str, method: &str, params: Value) -> Result<Value> {
+ start_idle_cleanup();
+ let dir = directory(bot)?;
+ let slot = PROCESSES.lock().await.entry(directory(bot)?.to_string_lossy().into_owned()).or_default().clone();
+ let mut process = slot.lock().await;
+ if let Some(p) = process.as_mut()
+ && p.child.try_wait()?.is_some()
+ {
+ *process = None;
+ }
+ if process.is_none() {
+ let binary = install::binary().await?;
+ super::migrate::run(&binary, &dir, &project(bot)).await?;
+ *process = Some(tokio::time::timeout(REQUEST_TIMEOUT, Process::start(&binary, &dir, &project(bot))).await??);
+ }
+ let result =
+ tokio::time::timeout(REQUEST_TIMEOUT, process.as_mut().context("Engram not running")?.request(method, params))
+ .await;
+ match result {
+ Ok(Ok(value)) => {
+ if let Some(p) = process.as_mut() {
+ p.last_used = Instant::now();
+ }
+ Ok(value)
+ }
+ failure => {
+ // Dropping stdin and the child closes the session. The next request starts fresh;
+ // replaying this request could duplicate a write whose acknowledgement was lost.
+ *process = None;
+ match failure {
+ Ok(Err(error)) => Err(error),
+ Err(error) => Err(anyhow!("Engram request timed out; check whether the change was saved: {error}")),
+ Ok(Ok(_)) => unreachable!(),
+ }
+ }
+ }
+}
+
+/// Stop the MCP writer while the native CLI removes all memory entities.
+pub(in crate::chat::memory) async fn clear(bot: &str) -> Result<()> {
+ prepare(bot).await?;
+ let slot = PROCESSES.lock().await.entry(directory(bot)?.to_string_lossy().into_owned()).or_default().clone();
+ let mut process = slot.lock().await;
+ if let Some(mut p) = process.take() {
+ p.child.kill().await?;
+ }
+ super::clear::run(bot).await
+}
+
+pub(in crate::chat::memory) async fn tools(bot: &str) -> Result<Value> {
+ request(bot, "tools/list", json!({})).await
+}
+
+pub(in crate::chat::memory) async fn prepare(bot: &str) -> Result<()> {
+ request(bot, "ping", json!({})).await?;
+ Ok(())
+}
+
+pub(in crate::chat::memory) async fn call(bot: &str, name: &str, args: &Value) -> Result<Value> {
+ ensure!(name.starts_with("mem_"), "unknown Engram tool");
+ request(bot, "tools/call", json!({"name":name, "arguments":args})).await
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[tokio::test]
+ #[ignore = "requires the pinned release binary at CODYNC_TEST_ENGRAM"]
+ async fn native_memory_survives_restart_and_cannot_read_another_bot() {
+ let binary = std::env::var("CODYNC_TEST_ENGRAM").expect("set CODYNC_TEST_ENGRAM");
+ let root = std::env::temp_dir().join(format!("codync-engram-test-{}", uuid::Uuid::new_v4()));
+ let result = async {
+ let mut a = Process::start(Path::new(&binary), &root.join("a"), "bot-a").await?;
+ let saved = a
+ .request(
+ "tools/call",
+ json!({"name":"mem_save", "arguments":{
+ "title":"使用者偏好", "type":"learning", "content":"使用者偏好繁體中文", "project":"bot-a"
+ }}),
+ )
+ .await?;
+ ensure!(saved["isError"] != true, "save failed: {saved}");
+ a.child.kill().await?;
+ drop(a);
+ let mut a = Process::start(Path::new(&binary), &root.join("a"), "bot-a").await?;
+ let query = json!({"name":"mem_search", "arguments":{"query":"繁體中文", "all_projects":true}});
+ let found = a.request("tools/call", query.clone()).await?;
+ ensure!(found.to_string().contains("使用者偏好"), "restart lost memory: {found}");
+ let mut b = Process::start(Path::new(&binary), &root.join("b"), "bot-b").await?;
+ let isolated = b.request("tools/call", query).await?;
+ ensure!(!isolated.to_string().contains("使用者偏好"), "cross-bot read: {isolated}");
+ a.child.kill().await?;
+ b.child.kill().await?;
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+ std::fs::remove_dir_all(root).expect("cleanup test databases");
+ result.expect("native Engram integration");
+ }
+}
diff --git a/host/src/chat/memory/extract.rs b/host/src/chat/memory/extract.rs
index 89206d26..b05ec6be 100644
--- a/host/src/chat/memory/extract.rs
+++ b/host/src/chat/memory/extract.rs
@@ -2,9 +2,7 @@
//! prompts (as in Grok Bot), parsing its reply and applying it to the memory folder.
use super::facts::{Fact, Kind, Memory, dedupe_key, normalize, ymd};
-use super::{
- ARCHIVE_SCAN_LIMIT, NONE, NOTE_PREFIX, PROFILE_PROMPT_LIMIT, PROFILE_TARGET, RECENT_PROMPT_LIMIT, RELEVANT_LIMIT,
-};
+use super::{NONE, NOTE_PREFIX, PROFILE_PROMPT_LIMIT, PROFILE_TARGET, RECENT_PROMPT_LIMIT, RELEVANT_LIMIT};
use crate::store::Store;
use anyhow::Result;
use serde::{Deserialize, Serialize};
@@ -163,44 +161,18 @@ fn strip_bullet(line: &str) -> &str {
t
}
-const STOPWORDS: &[&str] = &[
- "that", "this", "with", "from", "they", "them", "then", "than", "what", "when", "where", "which", "will", "would",
- "could", "should", "have", "been", "being", "about", "just", "like", "your", "does", "were", "also", "into",
- "over", "only", "some", "more", "most", "very", "much", "here", "there", "their", "these", "those", "because",
- "while", "after", "before", "user",
-];
-
-fn tokens(text: &str) -> HashSet<String> {
- text.to_lowercase()
- .split(|c: char| !c.is_alphanumeric())
- .filter(|w| w.chars().count() >= 4 && !STOPWORDS.contains(w))
- .map(str::to_owned)
- .collect()
-}
-
/// What the keeper is shown as "existing memory": everything in the prompt plus
/// archived facts that share words with the exchange.
-pub fn existing_for_extraction(mem: &Memory, exchange: &str) -> Vec<String> {
- let recall = mem.recall(RECENT_PROMPT_LIMIT);
+pub fn existing_for_extraction(mem: &Memory, exchange: &str) -> Result<Vec<String>> {
+ let recall = mem.recall(RECENT_PROMPT_LIMIT)?;
let in_prompt: Vec<&Fact> = recall.profile.iter().chain(&recall.recent).collect();
let shown: HashSet<String> = in_prompt.iter().map(|f| dedupe_key(&f.content)).collect();
- let query = tokens(exchange);
- let mut relevant: Vec<(usize, Fact)> = if query.is_empty() {
- Vec::new()
- } else {
- mem.list(ARCHIVE_SCAN_LIMIT)
- .into_iter()
- .filter(|f| !shown.contains(&dedupe_key(&f.content)))
- .map(|f| (tokens(&f.content).intersection(&query).count(), f))
- .filter(|(overlap, _)| *overlap > 0)
- .collect()
- };
- relevant.sort_by(|a, b| b.0.cmp(&a.0).then(b.1.created_at.cmp(&a.1.created_at)));
- in_prompt
+ let relevant = mem.relevant(exchange, RELEVANT_LIMIT)?;
+ Ok(in_prompt
.into_iter()
.map(|f| f.content.clone())
- .chain(relevant.into_iter().take(RELEVANT_LIMIT).map(|(_, f)| f.content))
- .collect()
+ .chain(relevant.into_iter().filter(|f| !shown.contains(&dedupe_key(&f.content))).map(|f| f.content))
+ .collect())
}
pub fn apply(mem: &Memory, ex: &Extraction, known: &[String], now: i64) -> Result<(usize, usize)> {
@@ -220,20 +192,22 @@ pub fn apply(mem: &Memory, ex: &Extraction, known: &[String], now: i64) -> Resul
Ok((added, removed))
}
-#[derive(Serialize, Deserialize, Clone, Debug)]
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
pub struct EpisodeTurn {
pub ts: i64,
pub user: String,
pub agent: String,
+ #[serde(default)]
+ pub session: String,
}
pub fn episode_system_prompt(bot_name: &str) -> String {
[
format!("You maintain the long-term memory of a personal assistant named {bot_name}."),
format!("You are given the most recent turns of a conversation between the user and {bot_name}, in order, each tagged with its date."),
- format!("Write ONE short journal-style sentence (two at most) capturing what the user and {bot_name} were actually working on across these turns — the throughline, key decisions, and outcomes — so it stays useful months from now."),
+ format!("Write a concise session summary of goals, decisions, outcomes and unfinished next steps capturing what the user and {bot_name} were actually working on across these turns — the throughline, key decisions, and outcomes — so it stays useful months from now."),
"Anchor any time references with the absolute dates shown, never relative words like \"yesterday\". Drop greetings, acknowledgements, and anything ephemeral. Never invent details.".to_owned(),
- "Output just the sentence(s), no preamble or bullets. Output exactly NONE if nothing in this stretch is worth remembering.".to_owned(),
+ "Output only the summary, no preamble. Output exactly NONE if nothing in this stretch is worth remembering.".to_owned(),
]
.join("\n")
}
@@ -270,7 +244,7 @@ pub fn set_pending_episode(store: &Store, bot_id: &str, turns: &[EpisodeTurn]) -
#[cfg(test)]
mod tests {
- use super::super::facts::parse_ymd;
+ use super::super::dates::parse_ymd;
use super::*;
#[test]
@@ -296,8 +270,8 @@ mod tests {
fn batched_exchanges_are_dated_in_order() {
let t = parse_ymd("2026-09-30").expect("valid date");
let turns = [
- EpisodeTurn { ts: t, user: "I use Swift 6".into(), agent: "Noted".into() },
- EpisodeTurn { ts: t, user: String::new(), agent: "Done".into() },
+ EpisodeTurn { ts: t, user: "I use Swift 6".into(), agent: "Noted".into(), session: String::new() },
+ EpisodeTurn { ts: t, user: String::new(), agent: "Done".into(), session: String::new() },
];
let prompt = extraction_user_prompt(&turns, &[]);
assert!(prompt.contains("Existing memory:\n(empty)"));
diff --git a/host/src/chat/memory/facts.rs b/host/src/chat/memory/facts.rs
index 52b8afdf..7ee03548 100644
--- a/host/src/chat/memory/facts.rs
+++ b/host/src/chat/memory/facts.rs
@@ -1,18 +1,19 @@
-//! The memory folder on disk: profile and dated log facts, read, added, removed and rewritten.
+//! Read-only projection of Engram's pinned schema for Codync's UI and prompt.
+//! These blocking methods run on `spawn_blocking`; every write uses native MCP.
-use super::{DAY_MS, LOG_DIR, LOG_HEADER, MAX_FACT_CHARS, PROFILE_FILE, PROFILE_HEADER, PROFILE_PROMPT_LIMIT, WRITES};
-use crate::LockExt;
-use anyhow::{Context as _, Result, anyhow, bail};
+use super::{MAX_FACT_CHARS, PROFILE_PROMPT_LIMIT, engram};
+use anyhow::{Context, Result, bail};
+use rusqlite::{Connection, OpenFlags};
use serde::{Deserialize, Serialize};
-use std::fmt::Write as _;
+use serde_json::{Value, json};
use std::path::{Path, PathBuf};
+pub use super::dates::ymd;
+
#[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Kind {
- /// Who the user is and how to work with them; kept indefinitely.
Profile,
- /// Dated history: projects, decisions, commitments, episodes, notes.
Log,
}
@@ -23,12 +24,16 @@ pub struct Fact {
pub content: String,
pub created_at: i64,
pub kind: Kind,
- #[serde(skip)]
- path: PathBuf,
- #[serde(skip)]
- line: usize,
- #[serde(skip)]
- order: usize,
+ pub title: String,
+ pub memory_type: String,
+ pub scope: String,
+ pub project: String,
+ pub topic_key: Option<String>,
+ pub session_id: String,
+ pub pinned: bool,
+ pub review_after: Option<String>,
+ pub revision_count: i64,
+ pub source: Option<String>,
}
pub struct Recall {
@@ -36,188 +41,155 @@ pub struct Recall {
pub recent: Vec<Fact>,
}
-/// One bot's memory folder.
pub struct Memory {
+ bot: String,
dir: PathBuf,
+ session: String,
}
impl Memory {
- pub fn for_bot(bot_id: &str) -> Result<Self> {
- // Bot ids are host-generated UUIDs; anything else must not become a path.
- if bot_id.is_empty() || !bot_id.chars().all(|c| c.is_ascii_alphanumeric() || c == '-') {
- bail!("invalid bot id");
+ pub fn for_bot(bot: &str) -> Result<Self> {
+ let dir = engram::directory(bot)?;
+ tokio::runtime::Handle::try_current()
+ .context("memory access requires a host runtime")?
+ .block_on(engram::prepare(bot))?;
+ Ok(Self { bot: bot.to_owned(), dir, session: format!("{}:codync-background", engram::project(bot)) })
+ }
+
+ pub fn for_session(bot: &str, session: &str) -> Result<Self> {
+ let mut memory = Self::for_bot(bot)?;
+ if !session.is_empty() {
+ session.clone_into(&mut memory.session);
}
- Ok(Self { dir: crate::service::data_dir().join("bots").join(bot_id).join("memory") })
- }
-
- #[cfg(test)]
- pub(super) fn at(dir: PathBuf) -> Self {
- Self { dir }
+ Ok(memory)
}
pub fn location(&self) -> &Path {
&self.dir
}
- fn profile_path(&self) -> PathBuf {
- self.dir.join(PROFILE_FILE)
+ pub fn project(&self) -> String {
+ engram::project(&self.bot)
}
- fn log_paths(&self) -> Vec<PathBuf> {
- let mut paths: Vec<PathBuf> = std::fs::read_dir(self.dir.join(LOG_DIR))
- .into_iter()
- .flatten()
- .flatten()
- .map(|e| e.path())
- .filter(|p| p.extension().is_some_and(|x| x == "md"))
- .collect();
- paths.sort();
- paths
+ fn database(&self) -> Result<Connection> {
+ let db = Connection::open_with_flags(self.dir.join("engram.db"), OpenFlags::SQLITE_OPEN_READ_ONLY)?;
+ db.busy_timeout(std::time::Duration::from_secs(5))?;
+ Ok(db)
}
- pub fn facts(&self) -> Vec<Fact> {
- let mut facts = parse_facts(&read(&self.profile_path()), Kind::Profile, &self.profile_path(), 0);
- for path in self.log_paths() {
- let base = facts.len();
- facts.extend(parse_facts(&read(&path), Kind::Log, &path, base));
- }
- facts
+ pub fn relevant(&self, query: &str, limit: usize) -> Result<Vec<Fact>> {
+ super::read::relevant(&self.database()?, query, limit)
}
- /// Newest first: every profile fact (capped) and the latest log facts.
- pub fn recall(&self, recent_limit: usize) -> Recall {
- let mut facts = self.facts();
- facts.sort_by(|a, b| b.created_at.cmp(&a.created_at).then(b.order.cmp(&a.order)));
- let (profile, recent): (Vec<Fact>, Vec<Fact>) = facts.into_iter().partition(|f| f.kind == Kind::Profile);
- Recall {
- profile: profile.into_iter().take(PROFILE_PROMPT_LIMIT).collect(),
- recent: recent.into_iter().take(recent_limit).collect(),
- }
+ pub fn browse(&self, query: &str, filter: &str, limit: usize, offset: usize) -> Result<super::read::Page> {
+ super::read::browse(&mut self.database()?, query, filter, limit, offset)
}
- /// Profile facts first, then newest.
- pub fn list(&self, limit: usize) -> Vec<Fact> {
- let mut facts = self.facts();
- facts.sort_by(|a, b| {
- (b.kind == Kind::Profile)
- .cmp(&(a.kind == Kind::Profile))
- .then(b.created_at.cmp(&a.created_at))
- .then(b.order.cmp(&a.order))
- });
- facts.truncate(limit);
- facts
+ pub fn find(&self, id: &str) -> Result<Fact> {
+ super::read::find(&self.database()?, id.parse()?)?.context("memory not found")
}
- pub fn profile_facts(&self) -> Vec<Fact> {
- parse_facts(&read(&self.profile_path()), Kind::Profile, &self.profile_path(), 0)
+ pub fn recall(&self, recent_limit: usize) -> Result<Recall> {
+ let db = self.database()?;
+ Ok(Recall {
+ profile: super::read::list(&db, "profile", PROFILE_PROMPT_LIMIT)?,
+ recent: super::read::list(&db, "log", recent_limit)?,
+ })
}
- fn log_path(&self, at_ms: i64) -> PathBuf {
- self.dir.join(LOG_DIR).join(format!("{}.md", &ymd(at_ms)[..7]))
+ pub fn profile_facts(&self) -> Result<Vec<Fact>> {
+ super::read::list(&self.database()?, "profile", usize::MAX)
}
- /// Replaces the profile with `keep`, moving `demote` to the log first (a crash
- /// in between leaves a duplicate, never a lost fact).
- pub fn rewrite_profile(&self, keep: &[(String, i64)], demote: &[(String, i64)]) -> Result<()> {
- let _g = WRITES.locked();
- for (content, at) in demote {
- append(&self.log_path(*at), LOG_HEADER, &normalize(content), *at)?;
- }
- let mut body = PROFILE_HEADER.to_owned();
- for (content, at) in keep {
- let _ = writeln!(body, "- ({}) {}", ymd(*at), normalize(content));
- }
- write_atomic(&self.profile_path(), &body)
- }
-
- /// Records a fact unless an equal one exists. Returns whether it was added.
pub fn add(&self, content: &str, kind: Kind, at_ms: i64) -> Result<bool> {
let content = normalize(content);
if content.is_empty() {
return Ok(false);
}
- let _g = WRITES.locked();
- if self.facts().iter().any(|f| dedupe_key(&f.content) == dedupe_key(&content)) {
+ if super::read::same_content(&self.database()?, &content)?.is_some() {
return Ok(false);
}
- let (path, header) = match kind {
- Kind::Profile => (self.profile_path(), PROFILE_HEADER),
- Kind::Log => (self.log_path(at_ms), LOG_HEADER),
- };
- append(&path, header, &content, at_ms)?;
+ self.tool(
+ "mem_save",
+ &json!({
+ "title": content.chars().take(100).collect::<String>(), "content": content,
+ "type": if kind == Kind::Profile { "learning" } else { "discovery" },
+ "scope": if kind == Kind::Profile { "personal" } else { "project" },
+ "project": engram::project(&self.bot), "capture_prompt": false,
+ "session_id": self.session,
+ "topic_key": format!("codync/keeper/{at_ms}/{}", super::read::content_hash(&content)),
+ }),
+ )?;
Ok(true)
}
+ pub fn summary(&self, content: &str) -> Result<()> {
+ self.tool(
+ "mem_session_summary",
+ &json!({"session_id":self.session, "project":self.project(), "content":content}),
+ )?;
+ Ok(())
+ }
+
pub fn remove(&self, id: &str) -> Result<bool> {
- let _g = WRITES.locked();
- let Some(fact) = self.facts().into_iter().find(|f| f.id == id) else { return Ok(false) };
- let mut lines: Vec<&str> = Vec::new();
- let raw = read(&fact.path);
- lines.extend(raw.split('\n'));
- if fact.line < lines.len() {
- lines.remove(fact.line);
- }
- write_atomic(&fact.path, &lines.join("\n"))?;
+ let Some(fact) = super::read::find(&self.database()?, id.parse()?)? else {
+ return Ok(false);
+ };
+ self.tool("mem_delete", &json!({"id":id.parse::<i64>()?, "expected_project":fact.project}))?;
Ok(true)
}
pub fn remove_by_content(&self, content: &str) -> Result<bool> {
- self.remove(&fact_id(&normalize(content)))
+ let Some(fact) = super::read::same_content(&self.database()?, content)? else {
+ return Ok(false);
+ };
+ self.remove(&fact.id)
}
pub fn clear(&self) -> Result<()> {
- let _g = WRITES.locked();
- match std::fs::remove_dir_all(self.dir.join(LOG_DIR)) {
- Err(e) if e.kind() != std::io::ErrorKind::NotFound => return Err(e.into()),
- _ => {}
- }
- write_atomic(&self.profile_path(), PROFILE_HEADER)
+ tokio::runtime::Handle::try_current()?.block_on(engram::clear(&self.bot))
}
-}
-fn append(path: &Path, header: &str, content: &str, at_ms: i64) -> Result<()> {
- let raw = read(path);
- let mut body = if raw.is_empty() { header.to_owned() } else { raw };
- if !body.ends_with('\n') {
- body.push('\n');
+ /// Consolidation changes the scope of old facts; their IDs and history remain intact.
+ pub fn rewrite_profile(&self, keep: &[(String, i64)], demote: &[(String, i64)]) -> Result<()> {
+ for (content, _) in demote {
+ if let Some(fact) = super::read::same_content(&self.database()?, content)? {
+ self.tool(
+ "mem_update",
+ &json!({"id":fact.id.parse::<i64>()?, "expected_project":fact.project, "scope":"project"}),
+ )?;
+ }
+ }
+ for (content, at) in keep {
+ if let Some(fact) = super::read::same_content(&self.database()?, content)? {
+ if fact.scope != "personal" {
+ self.tool(
+ "mem_update",
+ &json!({"id":fact.id.parse::<i64>()?, "expected_project":fact.project, "scope":"personal"}),
+ )?;
+ }
+ } else {
+ self.add(content, Kind::Profile, *at)?;
+ }
+ }
+ Ok(())
}
- let _ = writeln!(body, "- ({}) {content}", ymd(at_ms));
- write_atomic(path, &body)
-}
-fn read(path: &Path) -> String {
- std::fs::read_to_string(path).unwrap_or_default()
-}
-
-fn write_atomic(path: &Path, body: &str) -> Result<()> {
- let dir = path.parent().ok_or_else(|| anyhow!("memory path has no folder"))?;
- std::fs::create_dir_all(dir)?;
- let tmp = path.with_extension("md.tmp");
- std::fs::write(&tmp, body)?;
- std::fs::rename(&tmp, path).with_context(|| format!("writing {}", path.display()))
+ pub fn tool(&self, name: &str, args: &Value) -> Result<Value> {
+ let result = tokio::runtime::Handle::try_current()?.block_on(engram::call(&self.bot, name, args))?;
+ if result["isError"] == true {
+ bail!("Engram: {}", result["content"]);
+ }
+ Ok(result)
+ }
}
-fn parse_facts(raw: &str, kind: Kind, path: &Path, base: usize) -> Vec<Fact> {
- let mut out = Vec::new();
- for (line, text) in raw.split('\n').enumerate() {
- let Some(rest) = text.trim_end().strip_prefix("- (") else { continue };
- let Some((date, content)) = rest.split_once(") ") else { continue };
- let Some(created_at) = parse_ymd(date) else { continue };
- let content = normalize(content);
- if content.is_empty() {
- continue;
- }
- out.push(Fact {
- id: fact_id(&content),
- content,
- created_at,
- kind,
- path: path.to_owned(),
- line,
- order: base + out.len(),
- });
+pub(super) fn parse_timestamp(raw: &str) -> Result<i64> {
+ if let Ok(date) = chrono::DateTime::parse_from_rfc3339(raw) {
+ return Ok(date.timestamp_millis());
}
- out
+ Ok(chrono::NaiveDateTime::parse_from_str(raw, "%Y-%m-%d %H:%M:%S%.f")?.and_utc().timestamp_millis())
}
pub fn normalize(raw: &str) -> String {
@@ -228,103 +200,13 @@ pub(super) fn dedupe_key(content: &str) -> String {
normalize(content).to_lowercase()
}
-/// Stable id of a fact (FNV-1a of its dedupe key), so the same text is the same fact.
-fn fact_id(content: &str) -> String {
- let mut h: u64 = 0xcbf2_9ce4_8422_2325;
- for b in dedupe_key(content).bytes() {
- h ^= u64::from(b);
- h = h.wrapping_mul(0x0100_0000_01b3);
- }
- format!("{h:016x}")
-}
-
-// MARK: dates (UTC, no calendar crate needed)
-
-/// `YYYY-MM-DD` for a unix time in ms.
-pub fn ymd(ms: i64) -> String {
- if ms <= 0 {
- return "unknown date".into();
- }
- let z = ms.div_euclid(DAY_MS) + 719_468;
- let era = z.div_euclid(146_097);
- let doe = z - era * 146_097;
- let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
- let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
- let mp = (5 * doy + 2) / 153;
- let d = doy - (153 * mp + 2) / 5 + 1;
- let m = if mp < 10 { mp + 3 } else { mp - 9 };
- let y = yoe + era * 400 + i64::from(m <= 2);
- format!("{y:04}-{m:02}-{d:02}")
-}
-
-pub(super) fn parse_ymd(s: &str) -> Option<i64> {
- let mut parts = s.splitn(3, '-').map(str::parse::<i64>);
- let (y, m, d) = (parts.next()?.ok()?, parts.next()?.ok()?, parts.next()?.ok()?);
- if !(1..=12).contains(&m) || !(1..=31).contains(&d) {
- return None;
- }
- let y = if m <= 2 { y - 1 } else { y };
- let era = y.div_euclid(400);
- let yoe = y - era * 400;
- let doy = (153 * ((m + 9) % 12) + 2) / 5 + d - 1;
- let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
- Some((era * 146_097 + doe - 719_468) * DAY_MS)
-}
-
#[cfg(test)]
mod tests {
use super::*;
- use crate::chat::memory::tests::temp;
- use crate::chat::memory::{RECENT_PROMPT_LIMIT, render};
-
- #[test]
- fn dates_round_trip() {
- assert_eq!(ymd(0), "unknown date");
- assert_eq!(ymd(1_758_800_000_000), "2025-09-25");
- assert_eq!(ymd(951_782_400_000), "2000-02-29");
- for day in ["2024-02-29", "2026-01-01", "1999-12-31"] {
- assert_eq!(ymd(parse_ymd(day).expect("valid date")), day);
- }
- assert_eq!(parse_ymd("2026-13-01"), None);
- }
-
- #[test]
- fn facts_are_stored_deduped_and_removed() {
- let mem = temp();
- let t = parse_ymd("2026-09-25").expect("valid date");
- assert!(mem.add("The user's name is Kai", Kind::Profile, t).expect("add"));
- assert!(!mem.add("the user's name is kai", Kind::Profile, t).expect("add"));
- assert!(mem.add("Shipping Codync 2.2", Kind::Log, t).expect("add"));
- assert!(read(&mem.dir.join("log/2026-09.md")).contains("- (2026-09-25) Shipping Codync 2.2"));
- let recall = mem.recall(RECENT_PROMPT_LIMIT);
- assert_eq!(recall.profile.len(), 1);
- assert_eq!(recall.recent.len(), 1);
- let (text, has) = render(&recall, mem.location());
- assert!(has && text.contains("- (learned 2026-09-25) The user's name is Kai"));
- assert!(mem.remove_by_content("Shipping Codync 2.2").expect("remove"));
- assert!(mem.recall(10).recent.is_empty());
- mem.clear().expect("clear");
- assert!(mem.facts().is_empty());
- let _ = std::fs::remove_dir_all(&mem.dir);
- }
#[test]
- fn consolidation_moves_dropped_facts_to_the_log() {
- let mem = temp();
- let t = parse_ymd("2026-08-01").expect("valid date");
- for fact in ["Name is Kai", "Is called Kai", "Lives in Taipei"] {
- assert!(mem.add(fact, Kind::Profile, t).expect("add"));
- }
- let now = parse_ymd("2026-09-30").expect("valid date");
- mem.rewrite_profile(
- &[("The user's name is Kai".into(), now), ("Lives in Taipei".into(), t)],
- &[("Name is Kai".into(), t), ("Is called Kai".into(), t)],
- )
- .expect("rewrite");
- let profile: Vec<String> = mem.profile_facts().into_iter().map(|f| f.content).collect();
- assert_eq!(profile, ["The user's name is Kai", "Lives in Taipei"]);
- let log = read(&mem.dir.join("log/2026-08.md"));
- assert!(log.contains("- (2026-08-01) Name is Kai") && log.contains("- (2026-08-01) Is called Kai"));
- let _ = std::fs::remove_dir_all(&mem.dir);
+ fn reads_both_native_timestamp_formats_without_losing_date() {
+ assert_eq!(parse_timestamp("2026-01-01 00:00:00").unwrap(), parse_timestamp("2026-01-01T00:00:00Z").unwrap());
+ assert!(parse_timestamp("bad date").is_err());
}
}
diff --git a/host/src/chat/memory/keeper.rs b/host/src/chat/memory/keeper.rs
index 1f44051f..c398e77d 100644
--- a/host/src/chat/memory/keeper.rs
+++ b/host/src/chat/memory/keeper.rs
@@ -6,11 +6,8 @@ use super::extract::{
episode_user_prompt, existing_for_extraction, extraction_system_prompt, extraction_user_prompt, parse_extraction,
pending_episode, set_pending_episode,
};
-use super::facts::{Kind, Memory, dedupe_key, normalize};
-use super::{
- EPISODE_INTERVAL, EPISODE_PREFIX, EXCHANGE_CHARS, KEEPER_BATCH, KEEPER_IDLE, KEEPER_TIMEOUT, NONE,
- PROFILE_PROMPT_LIMIT,
-};
+use super::facts::{Kind, Memory, dedupe_key};
+use super::{EXCHANGE_CHARS, KEEPER_BATCH, KEEPER_IDLE, KEEPER_TIMEOUT, NONE, PROFILE_PROMPT_LIMIT};
use crate::agent::acp::{self, Acp, Incoming};
use crate::hub::Hub;
use crate::store::{BotConfig, Store};
@@ -26,6 +23,13 @@ pub struct Exchange {
pub user: String,
pub agent: String,
pub at: i64,
+ pub session: String,
+ pub revision: String,
+}
+
+pub enum KeeperEvent {
+ Exchange(Exchange),
+ Flush,
}
fn unprocessed_key(bot_id: &str) -> String {
@@ -42,8 +46,8 @@ fn unprocessed(store: &Store, bot_id: &str) -> Vec<EpisodeTurn> {
/// compaction or session anyway, and one run over several exchanges sees their
/// context. An unnamed bot is named right away (see `naming`). It stops when the
/// bot actor drops the sender; what's queued is picked up by the next keeper.
-pub fn spawn_keeper(hub: Arc<Hub>, bot_id: String) -> mpsc::UnboundedSender<Exchange> {
- let (tx, mut rx) = mpsc::unbounded_channel::<Exchange>();
+pub fn spawn_keeper(hub: Arc<Hub>, bot_id: String) -> mpsc::UnboundedSender<KeeperEvent> {
+ let (tx, mut rx) = mpsc::unbounded_channel::<KeeperEvent>();
tokio::spawn(async move {
let mut queued = unprocessed(&hub.store, &bot_id);
let idle = tokio::time::sleep(KEEPER_IDLE);
@@ -51,21 +55,31 @@ pub fn spawn_keeper(hub: Arc<Hub>, bot_id: String) -> mpsc::UnboundedSender<Exch
loop {
let flush = tokio::select! {
x = rx.recv() => {
- let Some(x) = x else { break };
+ let Some(event) = x else { break };
+ let KeeperEvent::Exchange(x) = event else {
+ idle.as_mut().reset(tokio::time::Instant::now());
+ continue;
+ };
+ if x.revision != super::maintenance::revision(&hub.store, &bot_id) { continue; }
let turn = EpisodeTurn {
ts: x.at,
user: acp::truncate(&x.user, EXCHANGE_CHARS),
agent: acp::truncate(&x.agent, EXCHANGE_CHARS),
+ session: x.session,
};
- if let Err(e) = crate::chat::naming::observe(&hub, &bot_id, turn.clone()).await {
- tracing::warn!(bot = %bot_id, error = format!("{e:#}"), "naming the bot failed");
- }
+ let mutation = super::maintenance::lock(&bot_id);
+ let guard = mutation.lock().await;
+ if x.revision != super::maintenance::revision(&hub.store, &bot_id) { continue; }
// Re-read: another keeper of this bot (before a restart) may have flushed.
queued = unprocessed(&hub.store, &bot_id);
- queued.push(turn);
+ queued.push(turn.clone());
if let Err(e) = hub.store.kv_set(&unprocessed_key(&bot_id), &serde_json::to_string(&queued).unwrap_or_default()) {
tracing::warn!(bot = %bot_id, error = format!("{e:#}"), "couldn't queue an exchange for memory");
}
+ drop(guard);
+ if let Err(e) = crate::chat::naming::observe(&hub, &bot_id, turn.clone()).await {
+ tracing::warn!(bot = %bot_id, error = format!("{e:#}"), "naming the bot failed");
+ }
idle.as_mut().reset(tokio::time::Instant::now() + KEEPER_IDLE);
queued.len() >= KEEPER_BATCH
}
@@ -74,57 +88,99 @@ pub fn spawn_keeper(hub: Arc<Hub>, bot_id: String) -> mpsc::UnboundedSender<Exch
if !flush {
continue;
}
- let batch = std::mem::take(&mut queued);
- // Cleared before the run: a failing agent must not retry the same batch forever.
- if let Err(e) = hub.store.kv_set(&unprocessed_key(&bot_id), "[]") {
- tracing::warn!(bot = %bot_id, error = format!("{e:#}"), "couldn't clear the memory queue");
- }
- if let Err(e) = remember(&hub, &bot_id, batch).await {
- tracing::warn!(bot = %bot_id, error = format!("{e:#}"), "memory keeper failed");
+ let processing = super::maintenance::keeper_lock(&bot_id);
+ let _processing = processing.lock().await;
+ queued = unprocessed(&hub.store, &bot_id);
+ match remember(&hub, &bot_id, queued.clone()).await {
+ Ok(()) => {
+ let mutation = super::maintenance::lock(&bot_id);
+ let _guard = mutation.lock().await;
+ let mut current = unprocessed(&hub.store, &bot_id);
+ acknowledge(&mut current, &queued);
+ if let Err(e) = hub
+ .store
+ .kv_set(&unprocessed_key(&bot_id), &serde_json::to_string(&current).unwrap_or_default())
+ {
+ tracing::warn!(bot = %bot_id, error = format!("{e:#}"), "couldn't acknowledge the memory queue");
+ } else {
+ queued = current;
+ }
+ }
+ Err(e) => {
+ tracing::warn!(bot = %bot_id, error = format!("{e:#}"), "memory keeper failed; batch retained for retry");
+ }
}
+ idle.as_mut().reset(tokio::time::Instant::now() + KEEPER_IDLE);
}
});
tx
}
+/// Another actor may have appended turns while an old keeper was working.
+fn acknowledge(current: &mut Vec<EpisodeTurn>, completed: &[EpisodeTurn]) {
+ if current.starts_with(completed) {
+ current.drain(..completed.len());
+ }
+}
+
async fn remember(hub: &Arc<Hub>, bot_id: &str, turns: Vec<EpisodeTurn>) -> Result<()> {
+ let mut groups = std::collections::BTreeMap::<String, Vec<EpisodeTurn>>::new();
+ for turn in pending_episode(&hub.store, bot_id).into_iter().chain(turns) {
+ groups.entry(turn.session.clone()).or_default().push(turn);
+ }
+ for (session, turns) in groups {
+ remember_session(hub, bot_id, &session, turns).await?;
+ }
+ set_pending_episode(&hub.store, bot_id, &[])?;
+ Ok(())
+}
+
+async fn remember_session(hub: &Arc<Hub>, bot_id: &str, session: &str, turns: Vec<EpisodeTurn>) -> Result<()> {
let Some(cfg) = hub.store.bot(bot_id)?.filter(|b| !b.deleted).map(|b| b.config) else { return Ok(()) };
let Some(at) = turns.last().map(|t| t.ts) else { return Ok(()) };
+ let revision = super::maintenance::revision(&hub.store, bot_id);
let id = bot_id.to_owned();
let exchange_text = turns.iter().map(|t| format!("{}\n{}", t.user, t.agent)).collect::<Vec<_>>().join("\n");
let existing = tokio::task::spawn_blocking(move || {
- Memory::for_bot(&id).map(|mem| existing_for_extraction(&mem, &exchange_text))
+ Memory::for_bot(&id).and_then(|mem| existing_for_extraction(&mem, &exchange_text))
})
.await??;
let raw = one_shot(hub, &cfg, &extraction_system_prompt(), &extraction_user_prompt(&turns, &existing)).await?;
let extraction = parse_extraction(&raw, &existing);
+ let mutation = super::maintenance::lock(bot_id);
+ let guard = mutation.lock().await;
+ if super::maintenance::revision(&hub.store, bot_id) != revision {
+ return Ok(()); // A user's edit/forget supersedes this extraction from old context.
+ }
let id = bot_id.to_owned();
+ let source_session =
+ if session.is_empty() { String::new() } else { super::lifecycle::begin(hub, bot_id, session).await? };
+ let summary_session = source_session.clone();
let (added, removed, crowded) = tokio::task::spawn_blocking(move || {
- Memory::for_bot(&id).and_then(|mem| {
+ Memory::for_session(&id, &source_session).and_then(|mem| {
let (added, removed) = apply(&mem, &extraction, &existing, at)?;
- Ok((added, removed, mem.profile_facts().len() > PROFILE_PROMPT_LIMIT))
+ Ok((added, removed, mem.profile_facts()?.len() > PROFILE_PROMPT_LIMIT))
})
})
.await??;
tracing::info!(bot = %bot_id, exchanges = turns.len(), added, removed, "memory updated");
- if crowded && let Err(e) = consolidate(hub, &cfg).await {
+ drop(guard);
+ if crowded && let Err(e) = consolidate(hub, &cfg, &revision).await {
tracing::warn!(bot = %bot_id, error = format!("{e:#}"), "consolidating the profile failed");
}
- let mut pending = pending_episode(&hub.store, bot_id);
- pending.extend(turns);
- if pending.len() < EPISODE_INTERVAL {
- return set_pending_episode(&hub.store, bot_id, &pending);
+ let raw = one_shot(hub, &cfg, &episode_system_prompt(&cfg.name), &episode_user_prompt(&cfg.name, &turns)).await?;
+ let narrative: String = raw.trim().chars().take(8_000).collect();
+ let _guard = mutation.lock().await;
+ if super::maintenance::revision(&hub.store, bot_id) != revision {
+ return Ok(());
}
- set_pending_episode(&hub.store, bot_id, &[])?;
- let raw = one_shot(hub, &cfg, &episode_system_prompt(&cfg.name), &episode_user_prompt(&cfg.name, &pending)).await?;
- let narrative = normalize(&raw);
if !narrative.is_empty() && !narrative.eq_ignore_ascii_case(NONE) {
- let at = pending.last().map_or(at, |t| t.ts);
let id = bot_id.to_owned();
tokio::task::spawn_blocking(move || {
- Memory::for_bot(&id).and_then(|mem| mem.add(&format!("{EPISODE_PREFIX}{narrative}"), Kind::Log, at))
+ let mem = Memory::for_session(&id, &summary_session)?;
+ mem.summary(&narrative)
})
.await??;
}
@@ -133,9 +189,9 @@ async fn remember(hub: &Arc<Hub>, bot_id: &str, turns: Vec<EpisodeTurn>) -> Resu
/// The profile outgrew what the prompt shows: have the keeper merge it down to
/// [`PROFILE_TARGET`] facts. Nothing is lost: facts it drops move to the log.
-async fn consolidate(hub: &Arc<Hub>, cfg: &BotConfig) -> Result<()> {
+async fn consolidate(hub: &Arc<Hub>, cfg: &BotConfig, revision: &str) -> Result<()> {
let id = cfg.id.clone();
- let facts = tokio::task::spawn_blocking(move || Memory::for_bot(&id).map(|m| m.profile_facts())).await??;
+ let facts = tokio::task::spawn_blocking(move || Memory::for_bot(&id).and_then(|m| m.profile_facts())).await??;
let raw = one_shot(hub, cfg, &consolidation_system_prompt(), &consolidation_user_prompt(&facts)).await?;
let plan = parse_extraction(&raw, &[]);
let keep: Vec<&String> = plan.additions.iter().filter(|(_, k)| *k == Kind::Profile).map(|(c, _)| c).collect();
@@ -152,6 +208,11 @@ async fn consolidate(hub: &Arc<Hub>, cfg: &BotConfig) -> Result<()> {
.map(|f| (f.content.clone(), f.created_at))
.collect();
demoted.extend(plan.additions.iter().filter(|(_, k)| *k == Kind::Log).map(|(c, _)| (c.clone(), now)));
+ let mutation = super::maintenance::lock(&cfg.id);
+ let _guard = mutation.lock().await;
+ if super::maintenance::revision(&hub.store, &cfg.id) != revision {
+ return Ok(());
+ }
let id = cfg.id.clone();
let (before, after) = (facts.len(), kept.len());
tokio::task::spawn_blocking(move || Memory::for_bot(&id).and_then(|m| m.rewrite_profile(&kept, &demoted)))
@@ -249,3 +310,18 @@ async fn collect(acp: &Acp, inc: Option<Incoming>, out: &mut String) -> bool {
}
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn acknowledging_a_batch_preserves_newer_or_replaced_work() {
+ let turn = |ts| EpisodeTurn { ts, user: "preference".into(), agent: "noted".into(), session: "session".into() };
+ let mut current = vec![turn(1), turn(2), turn(3)];
+ acknowledge(&mut current, &[turn(1), turn(2)]);
+ assert_eq!(current, vec![turn(3)]);
+ acknowledge(&mut current, &[turn(1)]);
+ assert_eq!(current, vec![turn(3)]);
+ }
+}
diff --git a/host/src/chat/memory/lifecycle.rs b/host/src/chat/memory/lifecycle.rs
new file mode 100644
index 00000000..5864989c
--- /dev/null
+++ b/host/src/chat/memory/lifecycle.rs
@@ -0,0 +1,88 @@
+//! Bind memory writes to the actual ACP session, including independent reply threads.
+
+use super::{engram, manage::payload};
+use crate::{
+ hub::Hub,
+ store::{Lane, lane_key},
+};
+use anyhow::{Context, Result, ensure};
+use serde_json::{Value, json};
+use std::sync::Arc;
+
+fn key(bot: &str, session: &str) -> String {
+ format!("memory.session.{bot}.{session}")
+}
+
+pub async fn begin(hub: &Arc<Hub>, bot: &str, session: &str) -> Result<String> {
+ let binding = key(bot, session);
+ let mut effective = hub.store.kv_get(&binding).filter(|v| !v.is_empty()).unwrap_or_else(|| session.to_owned());
+ for attempt in 0..2 {
+ let result =
+ engram::call(bot, "mem_session_start", &json!({"id":effective, "directory":engram::directory(bot)?}))
+ .await?;
+ if result["isError"] != true {
+ hub.store.kv_set(&binding, &effective)?;
+ return Ok(effective);
+ }
+ if attempt == 0 && payload(&result)["error_code"] == "session_already_ended" {
+ effective = format!("{session}:resume:{}", uuid::Uuid::new_v4());
+ } else {
+ anyhow::bail!("Engram session registration failed: {}", result["content"]);
+ }
+ }
+ anyhow::bail!("could not register memory session")
+}
+
+pub async fn bound_args(hub: &Arc<Hub>, bot: &str, lane: Option<&str>, name: &str, args: &Value) -> Result<Value> {
+ let row = hub.store.bot(bot)?.filter(|b| !b.deleted).context("unknown bot")?;
+ let sid = match lane.filter(|s| !s.is_empty()) {
+ Some(root) => hub.store.kv_get(&lane_key("session", bot, &Lane::in_thread(bot, root))),
+ None => row.session_id,
+ }
+ .filter(|s| !s.is_empty());
+ let mut args = args.clone();
+ ensure!(args.is_object(), "memory arguments must be an object");
+ // Search/management still works without a running agent (e.g. the settings screen).
+ if let Some(sid) = sid {
+ let effective = begin(hub, bot, &sid).await?;
+ if matches!(name, "mem_save" | "mem_save_prompt" | "mem_session_summary" | "mem_capture_passive") {
+ args["session_id"] = effective.clone().into();
+ }
+ if matches!(name, "mem_session_start" | "mem_session_end") {
+ args["id"] = effective.into();
+ }
+ }
+ if name == "mem_session_start" {
+ args["directory"] = json!(engram::directory(bot)?);
+ }
+ if args.get("project").is_some() {
+ args["project"] = engram::project(bot).into();
+ }
+ Ok(args)
+}
+
+pub async fn capture_prompt(bot: &str, session: &str, text: &str) -> Result<()> {
+ let result = engram::call(
+ bot,
+ "mem_save_prompt",
+ &json!({"session_id":session, "content":text, "project":engram::project(bot)}),
+ )
+ .await?;
+ ensure!(result["isError"] != true, "Engram prompt capture failed: {}", result["content"]);
+ Ok(())
+}
+
+/// An explicit edit/forget must reach non-Claude harnesses too, even mid-session.
+pub fn change_notice(hub: &Hub, bot: &str, session: &str) -> Option<String> {
+ let revision = super::maintenance::revision(&hub.store, bot);
+ let key = format!("memory.announced.{bot}.{session}");
+ if hub.store.kv_get(&key).unwrap_or_default() == revision {
+ return None;
+ }
+ Some("<memory_update>Saved memories have changed. Earlier memory excerpts may be outdated or deleted. Call mem_context and mem_search before relying on them; respect removals and corrections.</memory_update>".into())
+}
+
+/// A notice is acknowledged only after the prompt was delivered to the harness.
+pub fn mark_announced(hub: &Hub, bot: &str, session: &str, revision: &str) -> Result<()> {
+ hub.store.kv_set(&format!("memory.announced.{bot}.{session}"), revision)
+}
diff --git a/host/src/chat/memory/maintenance.rs b/host/src/chat/memory/maintenance.rs
new file mode 100644
index 00000000..a0e58188
--- /dev/null
+++ b/host/src/chat/memory/maintenance.rs
@@ -0,0 +1,38 @@
+//! Serialize forgetting against keeper writes, and invalidate every session's memory snapshot.
+
+use crate::{LockExt, store::Store};
+use anyhow::Result;
+use std::{
+ collections::HashMap,
+ sync::{Arc, LazyLock, Mutex},
+};
+
+static LOCKS: LazyLock<Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>>> =
+ LazyLock::new(|| Mutex::new(HashMap::new()));
+
+pub fn lock(bot: &str) -> Arc<tokio::sync::Mutex<()>> {
+ LOCKS.locked().entry(bot.to_owned()).or_default().clone()
+}
+
+pub fn keeper_lock(bot: &str) -> Arc<tokio::sync::Mutex<()>> {
+ static KEEPERS: LazyLock<Mutex<HashMap<String, Arc<tokio::sync::Mutex<()>>>>> =
+ LazyLock::new(|| Mutex::new(HashMap::new()));
+ KEEPERS.locked().entry(bot.to_owned()).or_default().clone()
+}
+
+pub fn revision(store: &Store, bot: &str) -> String {
+ store.kv_get(&format!("memory.revision.{bot}")).unwrap_or_default()
+}
+
+pub fn changed(store: &Store, bot: &str) -> Result<()> {
+ store.kv_set(&format!("memory.revision.{bot}"), &uuid::Uuid::new_v4().to_string())?;
+ for key in store.kv_prefix(&format!("context.{bot}.")) {
+ store.kv_set(&key, "")?;
+ }
+ Ok(())
+}
+
+pub fn discard_pending(store: &Store, bot: &str) -> Result<()> {
+ store.kv_set(&format!("memory.unprocessed.{bot}"), "[]")?;
+ super::set_pending_episode(store, bot, &[])
+}
diff --git a/host/src/chat/memory/manage.rs b/host/src/chat/memory/manage.rs
new file mode 100644
index 00000000..ddcda71d
--- /dev/null
+++ b/host/src/chat/memory/manage.rs
@@ -0,0 +1,163 @@
+//! Memory management shared by the phone, desktop and terminal clients.
+
+use super::{Memory, maintenance};
+use crate::hub::Hub;
+use anyhow::{Context, Result, bail, ensure};
+use serde_json::{Value, json};
+use std::sync::Arc;
+
+pub async fn call(hub: &Arc<Hub>, method: &str, args: &Value) -> Result<Value> {
+ let bot = args["botId"].as_str().context("botId is required")?.to_owned();
+ let row = hub.store.bot(&bot)?.filter(|b| !b.deleted && !b.config.is_group()).context("unknown bot")?;
+ let mutates = !matches!(method, "memory" | "memoryDetail" | "exportMemory");
+ let clears = method == "clearMemory";
+ let corrects = matches!(method, "saveMemory" | "forgetMemory");
+ let mutation = maintenance::lock(&bot);
+ let _guard = mutation.lock().await;
+ if clears {
+ // Invalidate before deletion too: partial native failures must not resurrect old queued facts.
+ maintenance::changed(&hub.store, &bot)?;
+ maintenance::discard_pending(&hub.store, &bot)?;
+ }
+ if method == "exportMemory" {
+ let text = serde_json::to_string_pretty(&super::engram::export(&bot).await?)?;
+ if text.len() <= 384 * 1024 {
+ return Ok(json!({"json":text}));
+ }
+ let id = uuid::Uuid::new_v4().to_string();
+ let root = crate::chat::uploads::root(&row.config);
+ let upload = id.clone();
+ tokio::task::spawn_blocking(move || {
+ crate::chat::uploads::append(&root, &upload, "engram-backup.json", 0, text.as_bytes(), true)
+ })
+ .await??;
+ return Ok(json!({"uploadId":id}));
+ }
+ if method == "importMemory" {
+ let data = if let Some(upload) = args["uploadId"].as_str() {
+ let root = crate::chat::uploads::root(&row.config);
+ let upload = upload.to_owned();
+ tokio::task::spawn_blocking(move || -> Result<Value> {
+ let (path, _) = crate::chat::uploads::resolve(&root, &upload)?;
+ ensure!(std::fs::metadata(&path)?.len() <= 100 * 1024 * 1024, "memory backup exceeds 100 MB");
+ Ok(serde_json::from_slice(&std::fs::read(path)?)?)
+ })
+ .await??
+ } else {
+ match args["json"].as_str() {
+ Some(text) => serde_json::from_str(text).context("invalid Engram JSON backup")?,
+ None => args["data"].clone(),
+ }
+ };
+ let result = super::engram::import(&bot, &data).await?;
+ maintenance::changed(&hub.store, &bot)?;
+ return Ok(result);
+ }
+ let (method, args, id) = (method.to_owned(), args.clone(), bot.clone());
+ let result = tokio::task::spawn_blocking(move || {
+ let memory = Memory::for_bot(&id)?;
+ dispatch(&memory, &method, &args)
+ })
+ .await??;
+ if mutates {
+ maintenance::changed(&hub.store, &bot)?;
+ }
+ if clears || corrects {
+ maintenance::discard_pending(&hub.store, &bot)?;
+ }
+ Ok(result)
+}
+
+fn dispatch(memory: &Memory, method: &str, args: &Value) -> Result<Value> {
+ match method {
+ "memory" => listing(memory, args),
+ "saveMemory" => save(memory, args),
+ "memoryDetail" => {
+ let fact = memory.find(required(args, "id")?)?;
+ let id = fact.id.parse::<i64>()?;
+ let mut history_args = json!({"id":id, "include_history":true, "project":fact.project});
+ if let Some(cursor) = args.get("historyCursor") {
+ history_args["history_cursor"] = cursor.clone();
+ }
+ let history = memory.tool("mem_get_observation", &history_args)?;
+ let timeline = memory.tool("mem_timeline", &json!({"observation_id":id, "project":fact.project}))?;
+ Ok(json!({"fact":fact, "history":payload(&history), "timeline":payload(&timeline)}))
+ }
+ "pinMemory" => {
+ let fact = memory.find(required(args, "id")?)?;
+ memory.tool(
+ if args["pinned"] == true { "mem_pin" } else { "mem_unpin" },
+ &json!({"id":fact.id.parse::<i64>()?}),
+ )?;
+ Ok(json!({}))
+ }
+ "reviewMemory" => {
+ let fact = memory.find(required(args, "id")?)?;
+ memory.tool(
+ "mem_review",
+ &json!({"action":"mark_reviewed", "observation_id":fact.id.parse::<i64>()?, "project":fact.project}),
+ )?;
+ Ok(json!({}))
+ }
+ "forgetMemory" => Ok(json!({"removed":memory.remove(required(args, "id")?)?})),
+ "clearMemory" => {
+ memory.clear()?;
+ Ok(json!({}))
+ }
+ _ => bail!("unknown memory operation"),
+ }
+}
+
+fn listing(memory: &Memory, args: &Value) -> Result<Value> {
+ let query = args["query"].as_str().unwrap_or_default().trim();
+ let offset = usize::try_from(args["offset"].as_u64().unwrap_or(0)).context("offset is too large")?;
+ // Old clients only send botId and have no Load more control.
+ let legacy = ["query", "filter", "offset", "limit"].iter().all(|key| args.get(key).is_none());
+ let limit = if legacy { usize::MAX } else { usize::try_from(args["limit"].as_u64().unwrap_or(50).clamp(1, 100))? };
+ let filter = args["filter"].as_str().unwrap_or("all");
+ let page = memory.browse(query, filter, limit, offset)?;
+ let next = (offset + page.facts.len() < page.total).then_some(offset + page.facts.len());
+ Ok(json!({"location":memory.location(), "engine":"engram", "version":super::engram::VERSION,
+ "facts":page.facts, "total":page.total, "nextOffset":next,
+ "query":query, "filter":filter, "offset":offset}))
+}
+
+fn save(memory: &Memory, args: &Value) -> Result<Value> {
+ let title = required(args, "title")?.trim();
+ let content = required(args, "content")?.trim();
+ ensure!(!title.is_empty() && !content.is_empty(), "title and content cannot be empty");
+ let scope = args["scope"].as_str().unwrap_or("project");
+ ensure!(["project", "personal", "global"].contains(&scope), "invalid memory scope");
+ let mut fields = json!({"title":title, "content":content, "scope":scope,
+ "type":args["memoryType"].as_str().unwrap_or("learning")});
+ if let Some(topic) = args["topicKey"].as_str() {
+ fields["topic_key"] = topic.into();
+ }
+ let name = if let Some(id) = args["id"].as_str() {
+ let existing = memory.find(id)?;
+ fields["id"] = id.parse::<i64>()?.into();
+ fields["expected_project"] = existing.project.into();
+ "mem_update"
+ } else {
+ fields["project"] = memory.project().into();
+ fields["capture_prompt"] = false.into();
+ fields["session_id"] = format!("{}:codync-background", memory.project()).into();
+ "mem_save"
+ };
+ Ok(payload(&memory.tool(name, &fields)?))
+}
+
+fn required<'a>(args: &'a Value, key: &str) -> Result<&'a str> {
+ args[key].as_str().with_context(|| format!("{key} is required"))
+}
+
+pub(super) fn payload(result: &Value) -> Value {
+ let text = result["content"]
+ .as_array()
+ .into_iter()
+ .flatten()
+ .filter_map(|v| v["text"].as_str())
+ .collect::<Vec<_>>()
+ .join("\n");
+ serde_json::from_str(&text).unwrap_or_else(|_| json!({"result":text}))
+}
diff --git a/host/src/chat/memory/mod.rs b/host/src/chat/memory/mod.rs
index ae2e22a6..8cba2d85 100644
--- a/host/src/chat/memory/mod.rs
+++ b/host/src/chat/memory/mod.rs
@@ -1,39 +1,28 @@
-//! A bot's long-term memory, modeled on Grok Bot's: plain markdown facts in
-//! `~/.codync/bots/<id>/memory/`: `profile.md` (who the user is, kept in mind
-//! every turn) and `log/YYYY-MM.md` (dated history), one `- (YYYY-MM-DD) fact`
-//! per line, so the user and the agent can read, grep and edit them.
-//!
-//! Memorable exchanges queue up for the bot's *keeper*, which runs a one-shot agent
-//! of the same harness over them once the bot goes quiet and extracts facts
-//! (`profile:` / `log:` / `note:` / `remove:`); every [`EPISODE_INTERVAL`]
-//! exchanges it also writes a one-line `[episode]` journal entry, and a profile
-//! that outgrows the prompt is consolidated. The bot sees memory through its
-//! frozen prompt (`context`) and searches its full chat with `search_history`.
+//! Per-bot Engram memory with automatic extraction, recall and native MCP tools.
+//! Transcripts stay in Codync; all durable memory lives in Engram's SQLite database.
+mod dates;
+mod engram;
mod extract;
mod facts;
mod keeper;
+pub(crate) mod lifecycle;
+pub(crate) mod maintenance;
+pub(crate) mod manage;
+mod read;
mod search;
pub use extract::{EpisodeTurn, is_memorable, set_pending_episode};
pub use facts::Memory;
pub(crate) use keeper::one_shot;
-pub use keeper::{Exchange, spawn_keeper};
-pub use search::{INSTRUCTIONS, call, tools};
+pub use keeper::{Exchange, KeeperEvent, spawn_keeper};
+pub use search::{INSTRUCTIONS, available_tools, call, tools};
use anyhow::Result;
use facts::{Fact, Recall, ymd};
-use serde_json::{Value, json};
use std::path::Path;
-use std::sync::Mutex;
use std::time::Duration;
-const PROFILE_FILE: &str = "profile.md";
-const LOG_DIR: &str = "log";
-const PROFILE_HEADER: &str =
- "# About the user\n\n<!-- Enduring facts, one per line as \"- (YYYY-MM-DD) <fact>\". -->\n\n";
-const LOG_HEADER: &str = "# Memory log\n\n<!-- Dated facts, one per line as \"- (YYYY-MM-DD) <fact>\". -->\n\n";
-
/// Profile facts shown in the prompt; past this the keeper consolidates the profile.
const PROFILE_PROMPT_LIMIT: usize = 100;
/// What a consolidation merges the profile down to, leaving room to grow.
@@ -42,11 +31,7 @@ const PROFILE_TARGET: usize = 60;
pub const RECENT_PROMPT_LIMIT: usize = 30;
const RECENT_CHAR_BUDGET: usize = 4_000;
const MAX_FACT_CHARS: usize = 500;
-/// Archived facts scanned for ones relevant to an exchange (beyond those in the prompt).
-const ARCHIVE_SCAN_LIMIT: usize = 500;
const RELEVANT_LIMIT: usize = 10;
-/// Exchanges per `[episode]` journal line.
-pub const EPISODE_INTERVAL: usize = 6;
/// An exchange side is cut to this before it goes to the keeper.
const EXCHANGE_CHARS: usize = 8_000;
const KEEPER_TIMEOUT: Duration = Duration::from_secs(180);
@@ -55,13 +40,8 @@ const KEEPER_IDLE: Duration = Duration::from_secs(5 * 60);
/// Queued exchanges that make the keeper run without waiting.
const KEEPER_BATCH: usize = 8;
-const EPISODE_PREFIX: &str = "[episode] ";
const NOTE_PREFIX: &str = "[note] ";
const NONE: &str = "NONE";
-const DAY_MS: i64 = 86_400_000;
-
-/// Serializes writes to memory files (the keeper and the API both write).
-static WRITES: Mutex<()> = Mutex::new(());
fn fact_line(f: &Fact) -> String {
format!("- (learned {}) {}", ymd(f.created_at), f.content)
@@ -73,10 +53,11 @@ pub fn render(recall: &Recall, location: &Path) -> (String, bool) {
"Memory: durable facts you have learned about the user and their world.".to_owned(),
"These persist across every session with this bot, even after a new session starts. Rely on them so you stay consistent and avoid re-asking what you already know.".to_owned(),
format!(
- "Your memory lives in a folder at {}: {PROFILE_FILE} holds who the user is (kept in mind every turn) and {LOG_DIR}/ holds dated history.",
+ "Your memory is managed by Engram in {}. Use its memory tools to read and write it; do not edit the database or the legacy Markdown backup directly.",
location.display()
),
- "Read or grep those files when you need older facts that are not listed here, and use the search_history tool to find what was actually said in past chats. Memory is updated automatically in the background shortly after each conversation: when the user asks you to remember or forget something, just confirm it to them and it will be recorded.".to_owned(),
+ "At the start of related work, call mem_context and mem_search to recall prior knowledge; retrieve full observations before relying on previews. Save durable preferences, decisions, discoveries and fixes proactively with mem_save. Reuse a stable topic_key for evolving knowledge. When asked to remember or forget, perform the memory operation before confirming success. A background keeper also extracts durable facts from completed user conversations.".to_owned(),
+ "Before ending a session, save a mem_session_summary. After compaction, recover context with mem_context. Use mem_review, mem_judge and mem_compare to review stale or conflicting knowledge; never treat a proposed conflict as resolved until it has been judged. Use search_history for original chat messages. Only this bot's memory is available through these tools.".to_owned(),
];
if !recall.profile.is_empty() {
lines.push("About the user:".into());
@@ -97,7 +78,7 @@ pub fn render(recall: &Recall, location: &Path) -> (String, bool) {
}
let omitted = recall.recent.len() - shown;
if omitted > 0 {
- lines.push(format!("({omitted} more log facts on disk — grep the {LOG_DIR}/ folder for them.)"));
+ lines.push(format!("({omitted} more recent memories — use mem_search to retrieve them.)"));
}
}
let has_facts = !recall.profile.is_empty() || !recall.recent.is_empty();
@@ -107,18 +88,7 @@ pub fn render(recall: &Recall, location: &Path) -> (String, bool) {
(lines.join("\n"), has_facts)
}
-/// `memory` API: the facts a bot has, for the Memory screen.
-pub fn describe(bot_id: &str) -> Result<Value> {
- let mem = Memory::for_bot(bot_id)?;
- Ok(json!({"location": mem.location(), "facts": mem.list(1_000)}))
-}
-
-#[cfg(test)]
-mod tests {
- use super::*;
-
- pub(super) fn temp() -> Memory {
- let dir = std::env::temp_dir().join(format!("codync-memory-{}", uuid::Uuid::new_v4()));
- Memory::at(dir)
- }
+/// Ensure installation, migration and the native memory process before starting a session.
+pub async fn prepare(bot_id: &str) -> Result<()> {
+ engram::prepare(bot_id).await
}
diff --git a/host/src/chat/memory/read.rs b/host/src/chat/memory/read.rs
new file mode 100644
index 00000000..226c5d79
--- /dev/null
+++ b/host/src/chat/memory/read.rs
@@ -0,0 +1,148 @@
+//! Bounded read-only queries over Engram's own indexes. Never creates or changes schema.
+
+use super::facts::{Fact, Kind};
+use anyhow::{Result, bail};
+use rusqlite::{Connection, Row, types::Value};
+use sha2::{Digest, Sha256};
+use std::fmt::Write as _;
+
+const COLUMNS: &str = "id, content, created_at, title, type, scope, project, topic_key,
+ session_id, pinned, review_after, revision_count, tool_name";
+const ORDER: &str = "pinned DESC, (scope = 'personal') DESC, created_at DESC, id DESC";
+
+pub struct Page {
+ pub facts: Vec<Fact>,
+ pub total: usize,
+}
+
+pub fn browse(db: &mut Connection, query: &str, filter: &str, limit: usize, offset: usize) -> Result<Page> {
+ let (condition, mut args) = conditions(query, filter)?;
+ let tx = db.transaction()?;
+ let total: i64 = tx.query_row(
+ &format!("SELECT COUNT(*) FROM observations WHERE {condition}"),
+ rusqlite::params_from_iter(&args),
+ |r| r.get(0),
+ )?;
+ args.push(Value::Integer(i64::try_from(limit).unwrap_or(i64::MAX)));
+ args.push(Value::Integer(i64::try_from(offset)?));
+ let facts = select(&tx, &format!("{condition} ORDER BY {ORDER} LIMIT ? OFFSET ?"), args)?;
+ tx.commit()?;
+ Ok(Page { facts, total: usize::try_from(total)? })
+}
+
+pub fn list(db: &Connection, filter: &str, limit: usize) -> Result<Vec<Fact>> {
+ let (condition, mut args) = conditions("", filter)?;
+ args.push(Value::Integer(i64::try_from(limit).unwrap_or(i64::MAX)));
+ select(db, &format!("{condition} ORDER BY {ORDER} LIMIT ?"), args)
+}
+
+pub fn find(db: &Connection, id: i64) -> Result<Option<Fact>> {
+ Ok(select(db, "deleted_at IS NULL AND id = ?", vec![Value::Integer(id)])?.pop())
+}
+
+/// Recall older relevant facts using Engram's FTS index instead of scanning a recent window.
+pub fn relevant(db: &Connection, text: &str, limit: usize) -> Result<Vec<Fact>> {
+ let mut terms = Vec::new();
+ let mut seen = std::collections::HashSet::new();
+ for word in text.split(|c: char| !c.is_alphanumeric()) {
+ let chars: Vec<char> = word.to_lowercase().chars().collect();
+ let candidates = if chars.iter().any(|c| ('\u{3400}'..='\u{9fff}').contains(c)) {
+ chars.windows(3).map(|w| w.iter().collect::<String>()).collect::<Vec<_>>()
+ } else if chars.len() >= 3 {
+ vec![chars.iter().collect()]
+ } else {
+ Vec::new()
+ };
+ for term in candidates {
+ if seen.insert(term.clone()) {
+ terms.push(format!("\"{}\"", term.replace('"', "\"\"")));
+ }
+ if terms.len() == 64 {
+ break;
+ }
+ }
+ if terms.len() == 64 {
+ break;
+ }
+ }
+ if terms.is_empty() {
+ return Ok(Vec::new());
+ }
+ select(
+ db,
+ "deleted_at IS NULL AND id IN (SELECT rowid FROM observations_fts WHERE observations_fts MATCH ? ORDER BY rank LIMIT ?)",
+ vec![Value::Text(terms.join(" OR ")), Value::Integer(i64::try_from(limit)?)],
+ )
+}
+
+pub fn same_content(db: &Connection, content: &str) -> Result<Option<Fact>> {
+ Ok(select(db, "deleted_at IS NULL AND normalized_hash = ? LIMIT 1", vec![Value::Text(content_hash(content))])?
+ .pop())
+}
+
+pub fn content_hash(content: &str) -> String {
+ let normalized = content.split_whitespace().collect::<Vec<_>>().join(" ").to_lowercase();
+ let mut hash = String::with_capacity(64);
+ for b in Sha256::digest(normalized.as_bytes()) {
+ let _ = write!(hash, "{b:02x}");
+ }
+ hash
+}
+
+fn select(db: &Connection, condition: &str, args: Vec<Value>) -> Result<Vec<Fact>> {
+ let mut query = db.prepare(&format!("SELECT {COLUMNS} FROM observations WHERE {condition}"))?;
+ Ok(query.query_map(rusqlite::params_from_iter(args), fact)?.collect::<rusqlite::Result<Vec<_>>>()?)
+}
+
+fn conditions(query: &str, filter: &str) -> Result<(String, Vec<Value>)> {
+ let mut clauses = vec!["deleted_at IS NULL".to_owned()];
+ match filter {
+ "profile" => clauses.push("scope = 'personal'".into()),
+ "log" => clauses.push("scope != 'personal'".into()),
+ "pinned" => clauses.push("pinned = 1".into()),
+ "review" => clauses.push("datetime(review_after) <= datetime('now')".into()),
+ "all" => {}
+ _ => bail!("unknown memory filter"),
+ }
+ let mut args = Vec::new();
+ let mut indexed = Vec::new();
+ // Engram uses a trigram FTS5 index. One/two-character terms need literal LIKE;
+ // escaping wildcards keeps punctuation and short CJK searches predictable.
+ for term in query.split_whitespace().take(16) {
+ if term.chars().count() >= 3 {
+ indexed.push(format!("\"{}\"", term.replace('"', "\"\"")));
+ } else {
+ let escaped = term.replace('\\', "\\\\").replace('%', "\\%").replace('_', "\\_");
+ clauses.push("(title || ' ' || content || ' ' || COALESCE(topic_key, '')) LIKE ? ESCAPE '\\'".into());
+ args.push(Value::Text(format!("%{escaped}%")));
+ }
+ }
+ if !indexed.is_empty() {
+ clauses.push("id IN (SELECT rowid FROM observations_fts WHERE observations_fts MATCH ?)".into());
+ args.push(Value::Text(indexed.join(" AND ")));
+ }
+ Ok((clauses.join(" AND "), args))
+}
+
+fn fact(row: &Row<'_>) -> rusqlite::Result<Fact> {
+ let scope: String = row.get(5)?;
+ let date: String = row.get(2)?;
+ let created_at = super::facts::parse_timestamp(&date)
+ .map_err(|e| rusqlite::Error::FromSqlConversionFailure(2, rusqlite::types::Type::Text, e.into()))?;
+ Ok(Fact {
+ id: row.get::<_, i64>(0)?.to_string(),
+ content: row.get(1)?,
+ created_at,
+ kind: if scope == "personal" { Kind::Profile } else { Kind::Log },
+ title: row.get(3)?,
+ memory_type: row.get(4)?,
+ scope,
+ project: row.get::<_, Option<String>>(6)?.unwrap_or_default(),
+ topic_key: row.get(7)?,
+ session_id: row.get(8)?,
+ pinned: row.get(9)?,
+ review_after: row.get(10)?,
+ revision_count: row.get(11)?,
+ source: row.get(12)?,
+ })
+}
diff --git a/host/src/chat/memory/search.rs b/host/src/chat/memory/search.rs
index 0333572f..9cf53789 100644
--- a/host/src/chat/memory/search.rs
+++ b/host/src/chat/memory/search.rs
@@ -33,6 +33,29 @@ pub fn tools() -> Value {
}
pub async fn call(hub: &Arc<Hub>, bot_id: &str, name: &str, args: &Value) -> Result<Value> {
+ hub.store.bot(bot_id)?.filter(|b| !b.deleted).ok_or_else(|| anyhow!("unknown bot"))?;
+ if name.starts_with("mem_") {
+ let read_only = matches!(
+ name,
+ "mem_search"
+ | "mem_context"
+ | "mem_timeline"
+ | "mem_get_observation"
+ | "mem_stats"
+ | "mem_current_project"
+ | "mem_list_projects"
+ | "mem_doctor"
+ | "mem_suggest_topic_key"
+ ) || (name == "mem_review" && args["action"] == "list");
+ let mutation = super::maintenance::lock(bot_id);
+ let _guard = if read_only { None } else { Some(mutation.lock().await) };
+ let result = super::engram::call(bot_id, name, args).await?;
+ if matches!(name, "mem_update" | "mem_delete" | "mem_merge_projects") && result["isError"] != true {
+ super::maintenance::changed(&hub.store, bot_id)?;
+ super::maintenance::discard_pending(&hub.store, bot_id)?;
+ }
+ return Ok(result);
+ }
if name != "search_history" {
bail!("unknown memory tool: {name}");
}
@@ -59,3 +82,11 @@ pub async fn call(hub: &Arc<Hub>, bot_id: &str, name: &str, args: &Value) -> Res
.collect();
Ok(json!({"results": results}))
}
+
+pub async fn available_tools(hub: &Arc<Hub>, bot_id: &str) -> Result<Value> {
+ hub.store.bot(bot_id)?.filter(|b| !b.deleted).ok_or_else(|| anyhow!("unknown bot"))?;
+ let mut native = super::engram::tools(bot_id).await?;
+ let list = native["tools"].as_array_mut().ok_or_else(|| anyhow!("Engram returned no tools"))?;
+ list.extend(tools().as_array().into_iter().flatten().cloned());
+ Ok(native)
+}
diff --git a/host/src/compat.rs b/host/src/compat.rs
index 9c8d97af..7743cfc3 100644
--- a/host/src/compat.rs
+++ b/host/src/compat.rs
@@ -10,7 +10,7 @@ use serde_json::Value;
pub const MIN_APP: &str = "2.3.0";
/// The oldest host the terminal client works with.
-pub const MIN_HOST: &str = "2.3.0";
+pub const MIN_HOST: &str = "2.12.0";
/// The iPhone app in the App Store, looked up to hold back host updates that need a newer
/// app than the store has (still in review).
diff --git a/host/src/mcp.rs b/host/src/mcp.rs
index b6f33584..1cad9f20 100644
--- a/host/src/mcp.rs
+++ b/host/src/mcp.rs
@@ -62,6 +62,7 @@ pub async fn serve(bot: String, port: u16, server: Server) -> Result<()> {
"ping" => Ok(json!({})),
"tools/list" => Ok(match server {
Server::Computer => computer_tools(port, &token).await,
+ Server::Memory => memory_tools(port, &token, &bot).await?,
_ => json!({"tools": available_tools}),
}),
"tools/call" => Ok(call(port, &token, &bot, params, server).await),
@@ -79,6 +80,19 @@ pub async fn serve(bot: String, port: u16, server: Server) -> Result<()> {
Ok(())
}
+async fn memory_tools(port: u16, token: &str, bot: &str) -> Result<Value> {
+ Ok(crate::http()
+ .post(format!("http://127.0.0.1:{port}/api/memoryTools"))
+ .bearer_auth(token)
+ .json(&json!({"botId": bot}))
+ .timeout(Duration::from_secs(240))
+ .send()
+ .await?
+ .error_for_status()?
+ .json()
+ .await?)
+}
+
/// The `computer` tools the host offers; none when it can't be reached.
async fn computer_tools(port: u16, token: &str) -> Value {
let res = crate::http()
@@ -98,6 +112,7 @@ async fn computer_tools(port: u16, token: &str) -> Value {
async fn call(port: u16, token: &str, bot: &str, params: &Value, server: Server) -> Value {
let body = json!({
"botId": bot,
+ "memoryLane": std::env::var("CODYNC_MEMORY_LANE").ok(),
"name": params["name"],
"arguments": params.get("arguments").filter(|a| a.is_object()).cloned().unwrap_or_else(|| json!({})),
});
@@ -107,7 +122,7 @@ async fn call(port: u16, token: &str, bot: &str, params: &Value, server: Server)
Server::Computer => ("computerCall", Duration::from_secs(60)),
Server::Chat => ("chatCall", Duration::from_secs(30)),
Server::Team => ("teamCall", crate::chat::team::ASK_TIMEOUT + Duration::from_secs(30)),
- Server::Memory => ("memoryCall", Duration::from_secs(30)),
+ Server::Memory => ("memoryCall", Duration::from_secs(120)),
Server::Composio => ("composioCall", Duration::from_secs(120)),
};
let res = crate::http()
@@ -125,6 +140,7 @@ async fn call(port: u16, token: &str, bot: &str, params: &Value, server: Server)
return match server {
Server::Computer if v["isError"] == true => json!({"content": v["content"], "isError": true}),
Server::Computer => json!({"content": v["content"]}),
+ Server::Memory if v["content"].is_array() => v,
Server::Chat | Server::Team | Server::Memory | Server::Routines | Server::Connectors => {
json!({"content": [{"type": "text", "text": v.to_string()}]})
}
diff --git a/host/src/tui/manage/memory.rs b/host/src/tui/manage/memory.rs
index d7e20d06..c3386548 100644
--- a/host/src/tui/manage/memory.rs
+++ b/host/src/tui/manage/memory.rs
@@ -1,40 +1,149 @@
-//! A bot's memory sheet.
+//! The same memory operations as the graphical clients, driven from the keyboard.
+use super::super::app::{App, Confirm, ConfirmAct, Editor, Overlay};
+use super::{Reply, ctrl, newline, s};
use crossterm::event::{KeyCode, KeyEvent};
-use serde_json::json;
+use serde_json::{Value, json};
-use super::super::app::{App, Confirm, ConfirmAct, Overlay};
-use super::{MemorySheet, Reply};
+pub const FILTERS: [&str; 4] = ["all", "profile", "pinned", "review"];
+
+pub struct MemorySheet {
+ pub bot: String,
+ pub facts: Option<Vec<Value>>,
+ pub cursor: usize,
+ pub query: String,
+ pub filter: usize,
+ pub offset: usize,
+ pub next_offset: Option<usize>,
+ pub total: usize,
+ pub mode: MemoryMode,
+ pub error: Option<String>,
+ pub busy: bool,
+}
+
+pub enum MemoryMode {
+ Browse,
+ Search(Editor),
+ Edit(MemoryForm),
+ Detail { text: String, scroll: usize, id: String, history_cursor: Option<i64> },
+ Export { text: String, scroll: usize },
+ Import(Editor),
+}
+
+pub struct MemoryForm {
+ pub id: Option<String>,
+ pub fields: [Editor; 5],
+ pub focus: usize,
+}
+
+impl MemorySheet {
+ pub fn body(&self) -> Value {
+ json!({"botId":self.bot, "query":self.query, "filter":FILTERS[self.filter], "offset":self.offset})
+ }
+
+ pub fn editor(&mut self) -> Option<&mut Editor> {
+ match &mut self.mode {
+ MemoryMode::Search(ed) | MemoryMode::Import(ed) => Some(ed),
+ MemoryMode::Edit(form) => Some(&mut form.fields[form.focus]),
+ _ => None,
+ }
+ }
+}
impl App {
pub fn open_memory(&mut self) {
- let Some(b) = self.bot().filter(|b| !b.group) else {
+ let Some(bot) = self.bot().filter(|b| !b.group).map(|b| b.id.clone()) else {
self.flash("A group has no memory of its own");
return;
};
- let bot = b.id.clone();
- self.sheet("memory", json!({"botId": bot}), Reply::Memory(bot.clone()));
- self.overlays.push(Overlay::Memory(MemorySheet { bot, facts: None, cursor: 0 }));
+ let m = MemorySheet {
+ bot: bot.clone(),
+ facts: None,
+ cursor: 0,
+ query: String::new(),
+ filter: 0,
+ offset: 0,
+ next_offset: None,
+ total: 0,
+ mode: MemoryMode::Browse,
+ error: None,
+ busy: true,
+ };
+ self.sheet("memory", m.body(), Reply::Memory(bot));
+ self.overlays.push(Overlay::Memory(m));
}
pub(in crate::tui) fn memory_key(&mut self, mut m: MemorySheet, k: KeyEvent) -> Option<Overlay> {
+ if !matches!(m.mode, MemoryMode::Browse) {
+ self.memory_mode_key(&mut m, k);
+ return Some(Overlay::Memory(m));
+ }
let n = m.facts.as_ref().map_or(0, Vec::len);
+ let selected = m.facts.as_ref().and_then(|f| f.get(m.cursor)).cloned();
match k.code {
KeyCode::Esc | KeyCode::Char('q' | 'M') => return None,
KeyCode::Down | KeyCode::Char('j') => m.cursor = (m.cursor + 1).min(n.saturating_sub(1)),
KeyCode::Up | KeyCode::Char('k') => m.cursor = m.cursor.saturating_sub(1),
- KeyCode::Char('x' | 'd') | KeyCode::Delete | KeyCode::Backspace => {
- if let Some(f) = m.facts.as_mut().filter(|f| m.cursor < f.len()) {
- let fact = f.remove(m.cursor);
- m.cursor = m.cursor.min(f.len().saturating_sub(1));
- self.sheet("forgetMemory", json!({"botId": m.bot, "id": fact.id}), Reply::Changed);
+ KeyCode::Char('/') => m.mode = MemoryMode::Search(Editor::with(&m.query)),
+ KeyCode::Char('f') => {
+ m.filter = (m.filter + 1) % FILTERS.len();
+ m.offset = 0;
+ self.load_memory(&mut m);
+ }
+ KeyCode::Char('r') => self.load_memory(&mut m),
+ KeyCode::Char(']') if m.next_offset.is_some() => {
+ m.offset = m.next_offset.unwrap_or(0);
+ self.load_memory(&mut m);
+ }
+ KeyCode::Char('[') => {
+ m.offset = m.offset.saturating_sub(50);
+ self.load_memory(&mut m);
+ }
+ KeyCode::Char('n') => m.mode = MemoryMode::Edit(form(None)),
+ KeyCode::Enter | KeyCode::Char('e') => {
+ if let Some(fact) = &selected {
+ m.mode = MemoryMode::Edit(form(Some(fact)));
+ }
+ }
+ KeyCode::Char('p' | 'v' | 'x') if !m.busy => {
+ if let Some(fact) = &selected {
+ let method = match k.code {
+ KeyCode::Char('p') => "pinMemory",
+ KeyCode::Char('v') => "reviewMemory",
+ _ => "forgetMemory",
+ };
+ m.busy = true;
+ self.sheet(
+ method,
+ json!({"botId":m.bot, "id":fact["id"], "pinned":fact["pinned"] != true}),
+ Reply::MemorySaved(m.bot.clone()),
+ );
+ }
+ }
+ KeyCode::Char('h') => {
+ if let Some(fact) = &selected {
+ m.mode = MemoryMode::Detail {
+ text: "Loading history…".into(),
+ scroll: 0,
+ id: s(fact, "id"),
+ history_cursor: None,
+ };
+ self.sheet(
+ "memoryDetail",
+ json!({"botId":m.bot, "id":fact["id"]}),
+ Reply::MemoryDetail(m.bot.clone()),
+ );
}
}
- KeyCode::Char('D') if n > 0 => {
- let name = self.bots.get(&m.bot).map_or_else(String::new, |b| b.name.clone());
+ KeyCode::Char('E') => {
+ m.mode = MemoryMode::Export { text: "Preparing backup…".into(), scroll: 0 };
+ self.sheet("exportMemory", json!({"botId":m.bot}), Reply::MemoryExport(m.bot.clone()));
+ }
+ KeyCode::Char('I') => m.mode = MemoryMode::Import(Editor::default()),
+ KeyCode::Char('D') if n > 0 && !m.busy => {
let c = Confirm {
- title: format!("Forget everything {name} remembers?"),
- detail: "Facts about you and its history go away.".into(),
+ title: "Forget everything this bot remembers?".into(),
+ detail: "Saved memories are removed.".into(),
note: "The chat stays.".into(),
button: "Forget everything",
act: ConfirmAct::ClearMemory(m.bot.clone()),
@@ -47,4 +156,85 @@ impl App {
}
Some(Overlay::Memory(m))
}
+
+ fn load_memory(&self, m: &mut MemorySheet) {
+ m.busy = true;
+ m.error = None;
+ self.sheet("memory", m.body(), Reply::Memory(m.bot.clone()));
+ }
+
+ fn memory_mode_key(&mut self, m: &mut MemorySheet, k: KeyEvent) {
+ if k.code == KeyCode::Esc {
+ m.mode = MemoryMode::Browse;
+ return;
+ }
+ match &mut m.mode {
+ MemoryMode::Search(ed) if k.code == KeyCode::Enter => {
+ m.query.clone_from(&ed.text);
+ m.offset = 0;
+ m.mode = MemoryMode::Browse;
+ self.load_memory(m);
+ }
+ MemoryMode::Edit(f) if k.code == KeyCode::Tab => f.focus = (f.focus + 1) % 5,
+ MemoryMode::Edit(f) if k.code == KeyCode::BackTab => f.focus = (f.focus + 4) % 5,
+ MemoryMode::Edit(f) if k.code == KeyCode::Char('s') && ctrl(k) && !m.busy => {
+ m.busy = true;
+ self.sheet(
+ "saveMemory",
+ json!({"botId":m.bot, "id":f.id,
+ "title":f.fields[0].text, "content":f.fields[1].text, "scope":f.fields[2].text,
+ "memoryType":f.fields[3].text, "topicKey":f.fields[4].text}),
+ Reply::MemorySaved(m.bot.clone()),
+ );
+ }
+ MemoryMode::Import(ed) if k.code == KeyCode::Char('s') && ctrl(k) && !m.busy => {
+ m.busy = true;
+ self.sheet("importMemory", json!({"botId":m.bot, "json":ed.text}), Reply::MemorySaved(m.bot.clone()));
+ }
+ MemoryMode::Detail { id, history_cursor: Some(cursor), .. } if k.code == KeyCode::Char('o') => {
+ self.sheet(
+ "memoryDetail",
+ json!({"botId":m.bot, "id":id, "historyCursor":cursor}),
+ Reply::MemoryDetail(m.bot.clone()),
+ );
+ }
+ MemoryMode::Detail { text, scroll, .. } | MemoryMode::Export { text, scroll } => match k.code {
+ KeyCode::Down | KeyCode::Char('j') => {
+ *scroll = (*scroll + 1).min(text.lines().count().saturating_sub(1));
+ }
+ KeyCode::Up | KeyCode::Char('k') => *scroll = scroll.saturating_sub(1),
+ KeyCode::Char('c') => {
+ super::super::app::copy(text);
+ self.flash("Copied");
+ }
+ _ => {}
+ },
+ _ => {
+ if let Some(ed) = m.editor() {
+ if newline(k) || k.code == KeyCode::Enter {
+ ed.insert("\n");
+ } else {
+ ed.key(k);
+ }
+ }
+ }
+ }
+ }
+}
+
+fn form(fact: Option<&Value>) -> MemoryForm {
+ MemoryForm {
+ id: fact.map(|f| s(f, "id")),
+ focus: 0,
+ fields: ["title", "content", "scope", "memoryType", "topicKey"].map(|key| {
+ Editor::with(&fact.map_or_else(
+ || match key {
+ "scope" => "project".into(),
+ "memoryType" => "learning".into(),
+ _ => String::new(),
+ },
+ |f| s(f, key),
+ ))
+ }),
+ }
}
diff --git a/host/src/tui/manage/mod.rs b/host/src/tui/manage/mod.rs
index 77051901..cfd7b3e8 100644
--- a/host/src/tui/manage/mod.rs
+++ b/host/src/tui/manage/mod.rs
@@ -12,6 +12,7 @@ mod memory;
mod replies;
mod routines;
+pub use memory::{MemoryMode, MemorySheet};
pub use routines::local_zone;
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
@@ -26,6 +27,9 @@ pub const REACTIONS: [&str; 6] = ["👍", "❤️", "😂", "🎉", "👀", "✅
#[derive(Clone)]
pub enum Reply {
Memory(String),
+ MemorySaved(String),
+ MemoryDetail(String),
+ MemoryExport(String),
Routines(String),
RoutineSaved,
/// A routine's webhook URL and key: copied as a ready-to-run curl.
@@ -44,18 +48,6 @@ pub enum Reply {
Changed,
}
-pub struct Fact {
- pub id: String,
- pub content: String,
- pub profile: bool,
-}
-
-pub struct MemorySheet {
- pub bot: String,
- pub facts: Option<Vec<Fact>>,
- pub cursor: usize,
-}
-
pub struct RoutineList {
pub bot: String,
pub items: Option<Vec<Value>>,
diff --git a/host/src/tui/manage/replies.rs b/host/src/tui/manage/replies.rs
index 95e6c541..e207be38 100644
--- a/host/src/tui/manage/replies.rs
+++ b/host/src/tui/manage/replies.rs
@@ -3,7 +3,7 @@
use serde_json::{Value, json};
use super::super::app::{After, App, Overlay, Toggle};
-use super::{Fact, Reply, Shell, open_browser, s};
+use super::{MemoryMode, Reply, Shell, open_browser, s};
impl App {
pub(in crate::tui) fn on_sheet_reply(&mut self, r: Reply, res: Result<Value, String>) {
@@ -20,14 +20,57 @@ impl App {
if let Overlay::Memory(m) = o
&& m.bot == bot
{
- let facts: Vec<Fact> = v["facts"]
- .as_array()
- .into_iter()
- .flatten()
- .map(|f| Fact { id: s(f, "id"), content: s(f, "content"), profile: f["kind"] == "profile" })
- .collect();
+ if v["query"].as_str() != Some(m.query.trim())
+ || v["filter"].as_str() != Some(super::memory::FILTERS[m.filter])
+ || v["offset"].as_u64() != Some(m.offset as u64)
+ {
+ continue;
+ }
+ let facts = v["facts"].as_array().cloned().unwrap_or_default();
m.cursor = m.cursor.min(facts.len().saturating_sub(1));
m.facts = Some(facts);
+ m.total = v["total"].as_u64().and_then(|n| usize::try_from(n).ok()).unwrap_or(0);
+ m.next_offset = v["nextOffset"].as_u64().and_then(|n| usize::try_from(n).ok());
+ m.busy = false;
+ m.error = None;
+ }
+ }
+ }
+ Reply::MemorySaved(bot) => {
+ for o in &mut self.overlays {
+ if let Overlay::Memory(m) = o
+ && m.bot == bot
+ {
+ m.mode = MemoryMode::Browse;
+ m.busy = false;
+ }
+ }
+ self.refresh_sheets();
+ }
+ Reply::MemoryDetail(bot) => {
+ for o in &mut self.overlays {
+ if let Overlay::Memory(m) = o
+ && m.bot == bot
+ {
+ m.mode = MemoryMode::Detail {
+ text: format!(
+ "{}\n\nSession timeline\n{}",
+ s(&v["history"], "result"),
+ s(&v["timeline"], "result")
+ ),
+ scroll: 0,
+ id: s(&v["fact"], "id"),
+ history_cursor: v["history"]["history_cursor"].as_i64(),
+ };
+ }
+ }
+ }
+ Reply::MemoryExport(bot) => {
+ for o in &mut self.overlays {
+ if let Overlay::Memory(m) = o
+ && m.bot == bot
+ {
+ m.mode = MemoryMode::Export { text: s(&v, "json"), scroll: 0 };
}
}
}
@@ -196,11 +239,16 @@ impl App {
m.error = Some(e);
}
}
- Reply::Memory(_) | Reply::Routines(_) => {
+ Reply::Memory(_)
+ | Reply::MemorySaved(_)
+ | Reply::MemoryDetail(_)
+ | Reply::MemoryExport(_)
+ | Reply::Routines(_) => {
for o in &mut self.overlays {
match o {
Overlay::Memory(m) => {
- m.facts.get_or_insert_with(Vec::new);
+ m.busy = false;
+ m.error = Some(e.clone());
}
Overlay::Routines(l) => {
l.items.get_or_insert_with(Vec::new);
@@ -220,7 +268,7 @@ impl App {
for o in &self.overlays {
match o {
Overlay::Memory(m) => {
- calls.push(("memory", json!({"botId": m.bot}), After::Sheet(Reply::Memory(m.bot.clone()))));
+ calls.push(("memory", m.body(), After::Sheet(Reply::Memory(m.bot.clone()))));
}
Overlay::Routines(l) => {
calls.push(("routines", json!({"botId": l.bot}), After::Sheet(Reply::Routines(l.bot.clone()))));
diff --git a/host/src/tui/net.rs b/host/src/tui/net.rs
index b075827e..2a48a45e 100644
--- a/host/src/tui/net.rs
+++ b/host/src/tui/net.rs
@@ -10,9 +10,10 @@ use tokio::sync::mpsc::UnboundedSender;
use super::app::{After, Msg};
use super::manage::Reply;
+mod memory_transfer;
/// Methods that start an agent or download something: they can take minutes.
-const SLOW: [&str; 7] = [
+const SLOW: [&str; 8] = [
"agentAuth",
"agentAuthenticate",
"agentModels",
@@ -20,6 +21,7 @@ const SLOW: [&str; 7] = [
"installConnector",
"installSkill",
"importConnectors",
+ "memory",
];
pub const NOT_INSTALLED: &str = "The Codync host isn't set up on this computer yet.";
@@ -59,7 +61,13 @@ impl Client {
.post(format!("{}/api/{method}", self.base))
.bearer_auth(&token)
.json(body)
- .timeout(Duration::from_secs(if SLOW.contains(&method) { 11 * 60 } else { 60 }))
+ .timeout(Duration::from_secs(
+ if SLOW.contains(&method) || method.starts_with("memory") || method.ends_with("Memory") {
+ 11 * 60
+ } else {
+ 60
+ },
+ ))
.send()
.await;
match sent {
@@ -82,7 +90,11 @@ impl Client {
pub fn spawn_call(&self, method: &'static str, body: Value, after: After, tx: UnboundedSender<Msg>) {
let c = self.clone();
tokio::spawn(async move {
- let r = c.call(method, &body).await;
+ let r = if matches!(method, "exportMemory" | "importMemory") {
+ memory_transfer::call(&c, method, &body).await
+ } else {
+ c.call(method, &body).await
+ };
let _ = tx.send(Msg::Reply(after, r));
});
}
diff --git a/host/src/tui/net/memory_transfer.rs b/host/src/tui/net/memory_transfer.rs
new file mode 100644
index 00000000..2d891268
--- /dev/null
+++ b/host/src/tui/net/memory_transfer.rs
@@ -0,0 +1,46 @@
+//! Large backups reuse the chunked file transport used by chat attachments.
+
+use super::Client;
+use base64::{Engine as _, engine::general_purpose::STANDARD};
+use serde_json::{Value, json};
+
+const CHUNK: usize = 384 * 1024;
+
+pub(super) async fn call(client: &Client, method: &str, body: &Value) -> Result<Value, String> {
+ if method == "importMemory" {
+ let text = body["json"].as_str().unwrap_or_default();
+ if text.len() > CHUNK {
+ let upload = uuid::Uuid::new_v4().to_string();
+ for (index, chunk) in text.as_bytes().chunks(CHUNK).enumerate() {
+ let offset = index * CHUNK;
+ client
+ .call(
+ "upload",
+ &json!({"botId":body["botId"], "uploadId":upload,
+ "name":"engram-backup.json", "data":STANDARD.encode(chunk), "offset":offset,
+ "done":offset + chunk.len() == text.len()}),
+ )
+ .await?;
+ }
+ return client.call(method, &json!({"botId":body["botId"], "uploadId":upload})).await;
+ }
+ }
+ let result = client.call(method, body).await?;
+ let Some(upload) = result["uploadId"].as_str().filter(|_| method == "exportMemory") else {
+ return Ok(result);
+ };
+ let mut bytes = Vec::new();
+ loop {
+ let chunk =
+ client.call("readUpload", &json!({"botId":body["botId"], "uploadId":upload, "offset":bytes.len()})).await?;
+ let data = STANDARD.decode(chunk["data"].as_str().unwrap_or_default()).map_err(|e| e.to_string())?;
+ if data.is_empty() {
+ return Err("Memory backup transfer ended early".into());
+ }
+ bytes.extend_from_slice(&data);
+ if bytes.len() as u64 >= chunk["size"].as_u64().unwrap_or(0) {
+ break;
+ }
+ }
+ Ok(json!({"json":String::from_utf8(bytes).map_err(|e| e.to_string())?}))
+}
diff --git a/host/src/tui/sheets.rs b/host/src/tui/sheets.rs
index 4ccec510..f70687d8 100644
--- a/host/src/tui/sheets.rs
+++ b/host/src/tui/sheets.rs
@@ -8,9 +8,12 @@ use ratatui::layout::{Position, Rect};
use ratatui::style::{Modifier, Style};
use serde_json::Value;
+mod memory_view;
+pub use memory_view::draw as memory;
+
use super::app::{App, Editor};
use super::manage::{
- AgentSetup, Fields, Market, MemorySheet, RoutineField, RoutineForm, RoutineList, Row, SetupRow, Submit, TABS, Tab,
+ AgentSetup, Fields, Market, RoutineField, RoutineForm, RoutineList, Row, SetupRow, Submit, TABS, Tab,
};
use super::md::truncate;
use super::view::{
@@ -51,39 +54,6 @@ fn name_of(app: &App, bot: &str) -> String {
app.bots.get(bot).map_or_else(String::new, |b| b.name.clone())
}
-pub fn memory(buf: &mut Buffer, area: Rect, app: &App, m: &MemorySheet) {
- let t = theme();
- let r = centered(area, 84, 24);
- let title = format!("{} remembers", name_of(app, &m.bot));
- let inner = frame_box(buf, r, t.text, t.panel, Some((&title, t.text)));
- let list_h = usize::from(inner.height.saturating_sub(3));
- match &m.facts {
- None => {
- put(buf, inner.x, inner.y + 1, inner.width, "Loading…", t.dim.patch(t.panel));
- }
- Some(f) if f.is_empty() => {
- put(
- buf,
- inner.x,
- inner.y + 1,
- inner.width,
- "Nothing yet. The bot remembers who you are and what you work on as you chat.",
- t.secondary.patch(t.panel),
- );
- }
- Some(facts) => {
- for (y, (i, f)) in (inner.y + 1..).zip(facts.iter().enumerate().skip(window(m.cursor, list_h)).take(list_h))
- {
- let base = row(buf, inner, y, i == m.cursor);
- put(buf, inner.x, y, 2, if f.profile { "●" } else { "◷" }, t.dim.patch(base));
- let room = usize::from(inner.width.saturating_sub(2));
- put(buf, inner.x + 2, y, u(room), &truncate(&f.content, room), t.text.patch(base));
- }
- }
- }
- footer(buf, inner, None, "● about you ◷ history · ↑↓ move · x forget · D forget everything · esc close");
-}
-
pub fn routines(buf: &mut Buffer, area: Rect, app: &App, l: &RoutineList) {
let t = theme();
let r = centered(area, 90, 24);
diff --git a/host/src/tui/sheets/memory_view.rs b/host/src/tui/sheets/memory_view.rs
new file mode 100644
index 00000000..bd6df6bc
--- /dev/null
+++ b/host/src/tui/sheets/memory_view.rs
@@ -0,0 +1,107 @@
+//! Memory browsing, editing and portable backups.
+
+use super::{App, Buffer, Rect, centered, footer, frame_box, input_line, name_of, put, row, s, theme, u, window};
+use crate::tui::manage::{MemoryMode, MemorySheet};
+use ratatui::widgets::{Paragraph, Widget, Wrap};
+
+pub fn draw(buf: &mut Buffer, area: Rect, app: &App, memory: &MemorySheet) {
+ let palette = theme();
+ let rect = centered(area, 100, 30);
+ let title = format!("{} · Memory", name_of(app, &memory.bot));
+ let inner = frame_box(buf, rect, palette.text, palette.panel, Some((&title, palette.text)));
+ let body = Rect::new(inner.x, inner.y + 1, inner.width, inner.height.saturating_sub(4));
+ let keys = match &memory.mode {
+ MemoryMode::Browse => {
+ browse(buf, body, memory);
+ "↑↓ move · / search · f filter · n add · ↵ edit · p pin · h history · v review · x forget"
+ }
+ MemoryMode::Search(editor) => {
+ input_line(buf, body, body.y, editor, "Search memories", true, false);
+ "Enter search · Esc cancel"
+ }
+ MemoryMode::Edit(form) => {
+ for (index, label) in
+ ["Title", "Memory", "Scope: personal / project / global", "Category", "Topic (optional)"]
+ .iter()
+ .enumerate()
+ {
+ let y = body.y + u(index * 3);
+ put(buf, body.x, y, body.width, label, palette.secondary.patch(palette.panel));
+ input_line(buf, body, y + 1, &form.fields[index], "", form.focus == index, false);
+ }
+ "Tab next field · Shift+Enter newline · Ctrl+S save · Esc cancel"
+ }
+ MemoryMode::Import(editor) => {
+ put(
+ buf,
+ body.x,
+ body.y,
+ body.width,
+ "Paste Engram JSON. Import merges; newer changes win. Backup saved first.",
+ palette.secondary,
+ );
+ input_line(buf, body, body.y + 2, editor, "JSON backup", true, false);
+ "Ctrl+S import · Esc cancel"
+ }
+ MemoryMode::Detail { text, scroll, .. } | MemoryMode::Export { text, scroll } => {
+ Paragraph::new(text.as_str())
+ .wrap(Wrap { trim: false })
+ .scroll((u(*scroll), 0))
+ .style(palette.text.patch(palette.panel))
+ .render(body, buf);
+ "↑↓ scroll · c copy · o older versions · Esc back"
+ }
+ };
+ if matches!(memory.mode, MemoryMode::Browse) {
+ put(
+ buf,
+ inner.x,
+ inner.bottom().saturating_sub(3),
+ inner.width,
+ "[ ] pages · r refresh · E export · I import · D clear · Esc close",
+ palette.dim.patch(palette.panel),
+ );
+ }
+ footer(buf, inner, memory.error.as_deref(), keys);
+}
+
+fn browse(buf: &mut Buffer, body: Rect, memory: &MemorySheet) {
+ let palette = theme();
+ let filter = ["All", "About you", "Pinned", "Needs review"][memory.filter];
+ let heading = format!(
+ "{filter} · {} memories · {}{}",
+ memory.total,
+ memory.query,
+ if memory.busy { " · Loading…" } else { "" }
+ );
+ put(buf, body.x, body.y, body.width, &heading, palette.secondary.patch(palette.panel));
+ let Some(facts) = &memory.facts else {
+ return;
+ };
+ if facts.is_empty() {
+ put(
+ buf,
+ body.x,
+ body.y + 2,
+ body.width,
+ "No matching memories. Important details are remembered as you chat.",
+ palette.secondary,
+ );
+ return;
+ }
+ let height = usize::from(body.height.saturating_sub(2)) / 2;
+ for (position, (index, fact)) in
+ facts.iter().enumerate().skip(window(memory.cursor, height)).take(height).enumerate()
+ {
+ let y = body.y + 2 + u(position * 2);
+ let base = row(buf, body, y, index == memory.cursor);
+ let title = format!(
+ "{}{} · {} revisions",
+ if fact["pinned"] == true { "● " } else { "" },
+ s(fact, "title"),
+ fact["revisionCount"]
+ );
+ put(buf, body.x, y, body.width, &title, palette.text.patch(base));
+ put(buf, body.x, y + 1, body.width, s(fact, "content"), palette.secondary.patch(palette.panel));
+ }
+}
diff --git a/host/src/tui/view/forms.rs b/host/src/tui/view/forms.rs
index 81d52a8d..00cf3ca0 100644
--- a/host/src/tui/view/forms.rs
+++ b/host/src/tui/view/forms.rs
@@ -129,7 +129,8 @@ pub(super) fn form_view(buf: &mut Buffer, area: Rect, app: &App, f: &Form) {
}
Field::Computer => {
let s = if f.computer { "◉ On ○ Off" } else { "○ On ◉ Off" };
- put(buf, vx, y, vw, s, t.text.patch(base));
+ let status = super::computer_access::status(&app.screen, app.online);
+ put(buf, vx, y, vw, &format!("{s} · {status}"), t.text.patch(base));
}
Field::Notify => {
let s = if f.notify { "◉ Done and needs-you ○ Off" } else { "○ Done and needs-you ◉ Off" };
@@ -172,6 +173,15 @@ pub(super) fn form_view(buf: &mut Buffer, area: Rect, app: &App, f: &Form) {
let by = inner.bottom() - 1;
if let Some(e) = &f.error {
put(buf, inner.x, by - 1, inner.width, e, t.red.patch(t.panel));
+ } else if f.current() == Field::Computer {
+ put(
+ buf,
+ inner.x,
+ by - 1,
+ inner.width,
+ "Set up on the computer: Codync → Settings → Computer access",
+ t.dim.patch(t.panel),
+ );
}
let save = if f.saving {
" … Saving "
diff --git a/host/tests/common/mod.rs b/host/tests/common/mod.rs
index f5eed406..4462d8e8 100644
--- a/host/tests/common/mod.rs
+++ b/host/tests/common/mod.rs
@@ -3,6 +3,17 @@
use std::process::{Child, Command};
use std::time::{Duration, Instant};
+/// Use the checksum-verified release fixture so isolated hosts don't each download it.
+pub fn seed_memory_runtime(home: &std::path::Path) {
+ let Some(binary) = std::env::var_os("CODYNC_TEST_ENGRAM") else {
+ return;
+ };
+ let dir = home.join("engram/3.2.1");
+ std::fs::create_dir_all(&dir).expect("memory runtime folder");
+ std::fs::copy(binary, dir.join(if cfg!(windows) { "engram.exe" } else { "engram" })).expect("copy Engram fixture");
+ std::fs::write(dir.join(".installed"), "3.2.1").expect("mark fixture installed");
+}
+
/// Stops a test host the way launchd does (SIGTERM), so it shuts down its own
/// children: a SIGKILL would orphan whatever it had running, such as a harness
/// sign-in check (`cursor-agent status` then spins forever). Kills it after 5 s.
diff --git a/host/tests/e2e.rs b/host/tests/e2e.rs
index 95db0fc5..765165f7 100644
--- a/host/tests/e2e.rs
+++ b/host/tests/e2e.rs
@@ -38,6 +38,7 @@ fn free_port() -> u16 {
async fn start_host() -> Host {
let home = std::env::temp_dir().join(format!("codync-e2e-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&home).unwrap();
+ common::seed_memory_runtime(&home);
let port = free_port();
let child = Command::new(env!("CARGO_BIN_EXE_codync-host"))
.args(["serve", "--bind", "127.0.0.1", "--port", &port.to_string()])
diff --git a/host/tests/fixtures/memory_agent.py b/host/tests/fixtures/memory_agent.py
new file mode 100644
index 00000000..bdbd3816
--- /dev/null
+++ b/host/tests/fixtures/memory_agent.py
@@ -0,0 +1,37 @@
+"""Deterministic ACP replies for automatic memory extraction, without an LLM provider."""
+import json
+import sys
+import uuid
+
+session = ""
+
+
+def send(value):
+ print(json.dumps({"jsonrpc": "2.0", **value}), flush=True)
+
+
+for line in sys.stdin:
+ request = json.loads(line)
+ method = request.get("method")
+ params = request.get("params", {})
+ if method == "initialize":
+ result = {"agentCapabilities": {"loadSession": True}}
+ elif method in ("session/new", "session/load"):
+ session = params.get("sessionId", str(uuid.uuid4()))
+ result = {"sessionId": session}
+ elif method == "session/prompt":
+ text = params["prompt"][0]["text"]
+ if "Tag each fact you keep with a category" in text:
+ reply = "profile: The user prefers concise Traditional Chinese explanations."
+ elif "Write a concise session summary" in text:
+ reply = "The user established a preference for concise Traditional Chinese explanations."
+ else:
+ reply = "I will use concise Traditional Chinese explanations."
+ send({"method": "session/update", "params": {"sessionId": session, "update": {
+ "sessionUpdate": "agent_message_chunk", "content": {"type": "text", "text": reply}
+ }}})
+ result = {"stopReason": "end_turn"}
+ else:
+ result = {}
+ if "id" in request:
+ send({"id": request["id"], "result": result})
diff --git a/host/tests/memory_e2e.rs b/host/tests/memory_e2e.rs
new file mode 100644
index 00000000..d9096e22
--- /dev/null
+++ b/host/tests/memory_e2e.rs
@@ -0,0 +1,230 @@
+//! A real host and a checksum-verified Engram release, with isolated disposable data.
+
+#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+#[allow(dead_code)]
+mod common;
+
+use base64::Engine as _;
+use serde_json::{Value, json};
+use std::{
+ fmt::Write as _,
+ path::PathBuf,
+ process::{Child, Command, Stdio},
+ time::{Duration, Instant},
+};
+
+struct Host {
+ child: Child,
+ home: PathBuf,
+ base: String,
+ token: String,
+}
+
+impl Drop for Host {
+ fn drop(&mut self) {
+ common::stop(&mut self.child);
+ let _ = std::fs::remove_dir_all(&self.home);
+ }
+}
+
+impl Host {
+ async fn start() -> Self {
+ assert!(std::env::var_os("CODYNC_TEST_ENGRAM").is_some(), "set CODYNC_TEST_ENGRAM to the pinned binary");
+ let home = std::env::temp_dir().join(format!("codync-memory-e2e-{}", uuid::Uuid::new_v4()));
+ common::seed_memory_runtime(&home);
+ let port = std::net::TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port();
+ let child = Command::new(env!("CARGO_BIN_EXE_codync-host"))
+ .args(["serve", "--bind", "127.0.0.1", "--port", &port.to_string()])
+ .env("CODYNC_HOME", &home)
+ .env("CODYNC_CLOUD", "off")
+ .stdout(Stdio::null())
+ .stderr(Stdio::null())
+ .spawn()
+ .unwrap();
+ let base = format!("http://127.0.0.1:{port}");
+ let deadline = Instant::now() + Duration::from_secs(20);
+ while reqwest::get(format!("{base}/health")).await.is_err() {
+ assert!(Instant::now() < deadline, "host did not start");
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ }
+ let token = std::fs::read_to_string(home.join("token")).unwrap().trim().to_owned();
+ Self { child, home, base, token }
+ }
+
+ async fn call(&self, method: &str, body: Value) -> Value {
+ let response = reqwest::Client::new()
+ .post(format!("{}/api/{method}", self.base))
+ .bearer_auth(&self.token)
+ .json(&body)
+ .timeout(Duration::from_secs(120))
+ .send()
+ .await
+ .unwrap();
+ let status = response.status();
+ let body: Value = response.json().await.unwrap();
+ assert!(status.is_success(), "{method}: {body}");
+ body
+ }
+
+ async fn bot(&self, name: &str) -> String {
+ self.call("createBot", json!({"name":name, "backend":"custom", "command":"unused", "connectors":[]}))
+ .await["bot"]["id"].as_str().unwrap().to_owned()
+ }
+}
+
+#[tokio::test]
+#[ignore = "requires the pinned Engram release at CODYNC_TEST_ENGRAM"]
+async fn migrate_manage_backup_and_forget_without_cross_bot_reads() {
+ let host = Host::start().await;
+ let a = host.bot("Memory A").await;
+ let b = host.bot("Memory B").await;
+ let legacy = host.home.join("bots").join(&a).join("memory");
+ std::fs::create_dir_all(legacy.join("log")).unwrap();
+ let mut facts = String::new();
+ for i in 0..65 {
+ writeln!(facts, "- (2026-01-01) 台灣繁體中文偏好 {i}").unwrap();
+ }
+ std::fs::write(legacy.join("profile.md"), &facts).unwrap();
+ std::fs::write(legacy.join("log/2026-02.md"), "- (2026-02-02) 發布 Codync\n").unwrap();
+
+ let first = host.call("memory", json!({"botId":a,"offset":0})).await;
+ assert_eq!(first["total"], 66);
+ assert_eq!(first["facts"].as_array().unwrap().len(), 50);
+ assert_eq!(first["nextOffset"], 50);
+ let legacy_client = host.call("memory", json!({"botId":a})).await;
+ assert_eq!(legacy_client["facts"].as_array().unwrap().len(), 66, "older clients cannot paginate");
+ let search = host.call("memory", json!({"botId":a, "query":"台灣繁體中文"})).await;
+ assert_eq!(search["total"], 65, "UI search must not inherit the MCP top-20 cap");
+ let short = host.call("memory", json!({"botId":a, "query":"台灣", "offset":50})).await;
+ assert_eq!(short["facts"].as_array().unwrap().len(), 15);
+ assert!(short["nextOffset"].is_null());
+ assert_eq!(host.call("memory", json!({"botId":b, "query":"台灣"})).await["total"], 0);
+ assert_eq!(std::fs::read_to_string(legacy.join("profile.md")).unwrap(), facts);
+ let one = &first["facts"][0];
+ assert_eq!(one["createdAt"], 1_767_225_600_000_i64);
+ let id = one["id"].as_str().unwrap();
+ host.call("saveMemory", json!({"botId":a,"id":id,"title":"Updated preference","content":"Prefers English now","scope":"personal","memoryType":"learning"})).await;
+ host.call("pinMemory", json!({"botId":a,"id":id,"pinned":true})).await;
+ let pinned = host.call("memory", json!({"botId":a,"filter":"pinned"})).await;
+ assert_eq!(pinned["total"], 1);
+ let detail = host.call("memoryDetail", json!({"botId":a,"id":id})).await;
+ assert!(detail["history"]["result"].as_str().unwrap().contains("台灣繁體中文"));
+ let exported = host.call("exportMemory", json!({"botId":a})).await;
+ let backup: Value = serde_json::from_str(exported["json"].as_str().unwrap()).unwrap();
+ assert_eq!(backup["observations"].as_array().unwrap().len(), 66);
+ host.call("forgetMemory", json!({"botId":a,"id":id})).await;
+ assert_eq!(host.call("memory", json!({"botId":a,"filter":"pinned"})).await["total"], 0);
+ let native_session = format!("codync-{a}:codync-background");
+ let prompt = host.call("memoryCall", json!({"botId":a,"name":"mem_save_prompt","arguments":{"session_id":native_session,"content":"UNIQUE_SECRET_CAPTURE"}})).await;
+ assert_ne!(prompt["isError"], true);
+ host.call("clearMemory", json!({"botId":a})).await;
+ let cleared = host.call("exportMemory", json!({"botId":a})).await;
+ let cleared: Value = serde_json::from_str(cleared["json"].as_str().unwrap()).unwrap();
+ assert!(!cleared.to_string().contains("UNIQUE_SECRET_CAPTURE"));
+ assert!(cleared["observations"].as_array().unwrap().is_empty());
+ assert_eq!(host.call("memory", json!({"botId":a})).await["total"], 0);
+ // Import into another bot's isolated store, then search the source content.
+ host.call("importMemory", json!({"botId":b,"json":exported["json"]})).await;
+ assert_eq!(host.call("memory", json!({"botId":b})).await["total"], 66);
+ assert_eq!(
+ host.call("memory", json!({"botId":a})).await["total"],
+ 0,
+ "legacy files must not resurrect cleared facts"
+ );
+}
+
+#[tokio::test]
+#[ignore = "requires the pinned Engram release at CODYNC_TEST_ENGRAM"]
+async fn large_backups_round_trip_through_chunked_transport() {
+ let host = Host::start().await;
+ let bot = host.bot("Large backup").await;
+ let session = "external-session";
+ let observations: Vec<Value> = (0..80)
+ .map(|i| {
+ json!({
+ "id":i+1, "sync_id":format!("large-{i}"), "session_id":session,
+ "project":"external-project", "title":format!("Durable fact {i}"), "type":"learning", "scope":"project",
+ "content":format!("Record {i}: {}", "long-lived knowledge ".repeat(500)),
+ "created_at":"2026-01-01T00:00:00Z", "updated_at":"2026-01-01T00:00:00Z",
+ })
+ })
+ .collect();
+ let backup = serde_json::to_vec(&json!({"version":"0.2.0", "sessions":[{
+ "id":session,"project":"external-project","directory":"", "started_at":"2026-01-01T00:00:00Z"
+ }],"observations":observations,"prompts":[]}))
+ .unwrap();
+ assert!(backup.len() > 384 * 1024);
+ let upload = uuid::Uuid::new_v4().to_string();
+ for (index, chunk) in backup.chunks(384 * 1024).enumerate() {
+ let offset = index * 384 * 1024;
+ host.call(
+ "upload",
+ json!({"botId":bot,"uploadId":upload,"name":"backup.json","offset":offset,
+ "data":base64::engine::general_purpose::STANDARD.encode(chunk),"done":offset+chunk.len()==backup.len()}),
+ )
+ .await;
+ }
+ host.call("importMemory", json!({"botId":bot,"uploadId":upload})).await;
+ assert_eq!(host.call("memory", json!({"botId":bot})).await["total"], 80);
+ let result = host.call("exportMemory", json!({"botId":bot})).await;
+ let upload = result["uploadId"].as_str().expect("large export must use chunks");
+ let mut bytes = Vec::new();
+ loop {
+ let part = host.call("readUpload", json!({"botId":bot,"uploadId":upload,"offset":bytes.len()})).await;
+ bytes.extend(base64::engine::general_purpose::STANDARD.decode(part["data"].as_str().unwrap()).unwrap());
+ if bytes.len() as u64 == part["size"].as_u64().unwrap() {
+ break;
+ }
+ }
+ let exported: Value = serde_json::from_slice(&bytes).unwrap();
+ assert_eq!(exported["observations"].as_array().unwrap().len(), 80);
+ for fact in exported["observations"].as_array().unwrap() {
+ assert_eq!(fact["project"], format!("codync-{bot}"));
+ assert!(fact["content"].as_str().unwrap().len() > 9_000);
+ }
+}
+
+#[tokio::test]
+#[ignore = "requires the pinned Engram release at CODYNC_TEST_ENGRAM"]
+async fn new_session_flushes_automatic_facts_and_native_summary() {
+ let host = Host::start().await;
+ let agent = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/memory_agent.py");
+ let command = common::python_agent(&agent);
+ let created = host
+ .call(
+ "createBot",
+ json!({"name":"Keeper test","backend":"custom","command":command,"connectors":[],"notify":false}),
+ )
+ .await;
+ let bot = created["bot"]["id"].as_str().unwrap();
+ host.call(
+ "send",
+ json!({"botId":bot,"text":"Please always explain things to me concisely in Traditional Chinese."}),
+ )
+ .await;
+ let deadline = Instant::now() + Duration::from_secs(30);
+ loop {
+ let history = host.call("history", json!({"botId":bot})).await;
+ if history["entries"].as_array().unwrap().iter().any(|e| e["kind"] == "agent" && e["data"]["final"] == true) {
+ break;
+ }
+ assert!(Instant::now() < deadline, "agent did not finish: {history}");
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ }
+ host.call("newSession", json!({"botId":bot})).await;
+ loop {
+ let memory = host.call("memory", json!({"botId":bot})).await;
+ let facts = memory["facts"].as_array().unwrap();
+ if facts.iter().any(|f| f["memoryType"] == "session_summary") {
+ assert!(
+ facts
+ .iter()
+ .any(|f| f["kind"] == "profile" && f["content"].as_str().unwrap().contains("Traditional Chinese"))
+ );
+ break;
+ }
+ assert!(Instant::now() < deadline, "keeper did not save summary: {memory}");
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ }
+}
diff --git a/host/tests/routines_e2e.rs b/host/tests/routines_e2e.rs
index 53c1505c..f70ad8ed 100644
--- a/host/tests/routines_e2e.rs
+++ b/host/tests/routines_e2e.rs
@@ -28,6 +28,7 @@ impl Host {
async fn start() -> Self {
let home = std::env::temp_dir().join(format!("codync-routines-e2e-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&home).unwrap();
+ common::seed_memory_runtime(&home);
let port = std::net::TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port();
let child = Command::new(env!("CARGO_BIN_EXE_codync-host"))
.args(["serve", "--bind", "127.0.0.1", "--port", &port.to_string()])
diff --git a/host/tests/team_e2e.rs b/host/tests/team_e2e.rs
index d8b4cb44..9868f383 100644
--- a/host/tests/team_e2e.rs
+++ b/host/tests/team_e2e.rs
@@ -28,6 +28,7 @@ impl Host {
async fn start() -> Self {
let home = std::env::temp_dir().join(format!("codync-team-e2e-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&home).unwrap();
+ common::seed_memory_runtime(&home);
let port = std::net::TcpListener::bind("127.0.0.1:0").unwrap().local_addr().unwrap().port();
let child = Command::new(env!("CARGO_BIN_EXE_codync-host"))
.args(["serve", "--bind", "127.0.0.1", "--port", &port.to_string()])
diff --git a/packaging/engram/release.json b/packaging/engram/release.json
new file mode 100644
index 00000000..c2ead93a
--- /dev/null
+++ b/packaging/engram/release.json
@@ -0,0 +1,11 @@
+{
+ "version": "3.2.1",
+ "assets": {
+ "darwin_amd64": "bc529ce47844a59c8091ca444e5f3f1ba126caf8df5b4dff01312df345c5c3f9",
+ "darwin_arm64": "32901d25a1a311565c382111f138fc7788e80685e575e9ec11e7c2ae5fbc5128",
+ "linux_amd64": "c5e0bbf77b3c4b196713d64d68593966d30a94582fad8dafe8e458a182c155a8",
+ "linux_arm64": "e1ed861f8e745bd93e679a91e283ae6668e64ad0afcdd552f61625d0e45480dd",
+ "windows_amd64": "d1951fec7810e5ff2213a24865c3ee63b7ecfd10a4b8631494faf02d1c2eae65",
+ "windows_arm64": "8d09fe37b22c02ac3717751a083b20af99e60f43d919e9e6bcde50e2827cabec"
+ }
+}
diff --git a/packaging/engram/test-runtime.py b/packaging/engram/test-runtime.py
new file mode 100644
index 00000000..9af9621f
--- /dev/null
+++ b/packaging/engram/test-runtime.py
@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Fetch the same pinned Engram release as the host for isolated integration tests."""
+
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import platform
+import tarfile
+import urllib.request
+import zipfile
+
+root = Path(__file__).resolve().parents[2]
+release = json.loads((Path(__file__).parent / "release.json").read_text())
+system = {"Darwin": "darwin", "Linux": "linux", "Windows": "windows"}[platform.system()]
+arch = {"arm64": "arm64", "aarch64": "arm64", "x86_64": "amd64", "amd64": "amd64"}[platform.machine().lower()]
+target = f"{system}_{arch}"
+version = release["version"]
+extension = "zip" if system == "windows" else "tar.gz"
+name = "engram.exe" if system == "windows" else "engram"
+archive = f"engram_{version}_{target}.{extension}"
+url = f"https://github.com/Gentleman-Programming/engram/releases/download/v{version}/{archive}"
+with urllib.request.urlopen(url, timeout=120) as response:
+ data = response.read(128 * 1024 * 1024 + 1)
+if hashlib.sha256(data).hexdigest() != release["assets"][target]:
+ raise SystemExit("Engram release checksum mismatch")
+destination = root / "host" / "target" / "engram-test-runtime" / version / name
+destination.parent.mkdir(parents=True, exist_ok=True)
+if extension == "zip":
+ with zipfile.ZipFile(io.BytesIO(data)) as files:
+ binary = files.read(name)
+else:
+ with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as files:
+ member = files.getmember(name)
+ if not member.isfile():
+ raise SystemExit("Engram release does not contain a regular binary")
+ binary = files.extractfile(member).read()
+destination.write_bytes(binary)
+destination.chmod(0o755)
+if "GITHUB_ENV" in os.environ:
+ with open(os.environ["GITHUB_ENV"], "a", encoding="utf-8") as env:
+ env.write(f"CODYNC_TEST_ENGRAM={destination}\n")
+print(destination)