@atmem/architect 0.0.0-stage → 0.2.0

package/server/memory_context.py

@@ -0,0 +1,58 @@
+"""Operator-configured external RAG/memory retrieval; never persists returned context."""
+from concurrent.futures import ThreadPoolExecutor
+import json
+import os
+import re
+from urllib.parse import urlsplit
+import urllib.request
+from .settings import setting
+
+
+def providers():
+    values=json.loads(setting('MEMORY_CONTEXT_PROVIDERS') or '[]')
+    if not isinstance(values,list)or len(values)>4:raise ValueError('Configure at most four context providers')
+    seen=set()
+    for value in values:
+        if not isinstance(value,dict)or set(value)-{'id','label','url','tokenEnv','enabled','kind'}:raise ValueError('Invalid context provider configuration')
+        ident=value.get('id','');url=urlsplit(value.get('url',''))
+        if not re.fullmatch(r'[a-z][a-z0-9-]{0,63}',ident)or ident in seen or url.scheme not in {'http','https'}or not url.hostname or url.username or url.password or url.fragment or url.query:raise ValueError('Context providers need unique IDs and credential-free HTTP endpoints')
+        token=value.get('tokenEnv')
+        if token and not re.fullmatch(r'[A-Z][A-Z0-9_]{0,99}',token):raise ValueError('Use an environment variable for provider credentials')
+        seen.add(ident)
+    return values
+
+
+def describe():
+    return [{'id':value['id'],'label':str(value.get('label')or value['id'])[:80],'kind':value.get('kind','rag'),'enabled':value.get('enabled',True),'configured':True}for value in providers()]
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self,*args,**kwargs):return None
+
+
+def retrieve(project,owner,query,safe):
+    configured=[value for value in providers()if value.get('enabled',True)]
+    if not configured:return [],[]
+    def fetch(value):
+        ident=value['id'];headers={'Content-Type':'application/json'}
+        if value.get('tokenEnv'):
+            token=os.getenv(value['tokenEnv'])
+            if not token:return [],{'id':ident,'status':'credential_missing'}
+            headers['Authorization']='Bearer '+token
+        request=urllib.request.Request(value['url'],data=json.dumps({'query':query[:4000],'userId':owner,'projectId':project,'limit':6}).encode(),headers=headers,method='POST')
+        try:
+            with urllib.request.build_opener(NoRedirect).open(request,timeout=4)as response:data=response.read(100001)
+            if len(data)>100000:raise ValueError('Context exceeds bound')
+            result=json.loads(data);rows=result.get('records')
+            if not isinstance(rows,list)or len(rows)>6:raise ValueError('Invalid context response')
+            context=[]
+            for row in rows:
+                scope=row.get('scope','project')
+                if scope not in {'project','user'}or row.get('userId')!=owner or(scope=='project'and row.get('projectId')!=project)or(scope=='user'and row.get('projectId')not in {None,''}):raise ValueError('Context scope mismatch')
+                text=row.get('text');source=row.get('source');record_id=row.get('id')
+                if not isinstance(text,str)or not 0<len(text)<=4000 or not safe(text)or not isinstance(source,dict)or not isinstance(record_id,str)or len(record_id)>160 or not safe(source):raise ValueError('Invalid context provenance')
+                context.append({'id':ident+':'+record_id,'scope':scope,'text':text,'sourceDate':row.get('createdAt'),'key':row.get('key'),'provider':ident,'source':source,'external':True,'boundary':'retrieved_context_only'})
+            return context,{'id':ident,'status':'ready','records':len(context)}
+        except Exception:return [],{'id':ident,'status':'unavailable'}
+    with ThreadPoolExecutor(max_workers=4)as pool:results=list(pool.map(fetch,configured))
+    return [row for rows,_ in results for row in rows],[state for _,state in results]

package/server/memory_routes.py

@@ -0,0 +1,141 @@
+"""All memory requests pass the existing loopback + bearer middleware."""
+import asyncio
+from fastapi import APIRouter, HTTPException
+from pydantic import Field, StrictBool
+from typing import Literal
+from .contracts import Strict
+from .memory_service import service
+from . import skills
+from .pricing import aws_s3, storage_quote, lambda_quote, google_public_quote
+
+router=APIRouter()
+class Target(Strict):
+    projectId:str=Field(pattern=r'^[A-Za-z0-9-]{8,64}$')
+class Snapshot(Target):
+    file:dict
+class Setting(Target):
+    enabled:StrictBool
+class Profile(Target):
+    field:Literal['explanation','experience','iac','preferences']
+    value:str=Field(min_length=1,max_length=1000)
+class Forget(Target):
+    scope:Literal['user','project']
+    recordId:str=Field(pattern=r'^rec_[a-f0-9]{32}$')
+class Skill(Target):
+    skillId:str=Field(max_length=80)
+    enabled:StrictBool
+class Price(Target):
+    provider:Literal['aws','azure','gcp','ibm']='aws'
+    region:str=Field(max_length=40)
+
+async def invoke(fn,*args,**kwargs):
+    try:return await asyncio.to_thread(fn,*args,**kwargs)
+    except ValueError as exc:raise HTTPException(422,str(exc))
+    except Exception:raise HTTPException(503,'AtMem is unavailable; your project still works. Run npm run setup:memory if needed.')
+
+@router.post('/api/memory/sync')
+async def sync(payload:Snapshot):
+    return await invoke(service().sync,payload.projectId,payload.file)
+
+@router.post('/api/memory/inspect')
+async def inspect(payload:Target):
+    memory=service()
+    result=await invoke(memory.inspect,payload.projectId)
+    result['skills']=skills.public(skills.catalogue(memory,payload.projectId))
+    return result
+
+@router.post('/api/memory/settings')
+async def settings(payload:Setting):
+    return await invoke(service().configure,payload.projectId,payload.enabled)
+
+@router.post('/api/memory/profile')
+async def profile(payload:Profile):
+    return await invoke(service().profile,payload.projectId,payload.field,payload.value)
+
+@router.post('/api/memory/forget-preview')
+async def preview(payload:Forget):
+    result=await invoke(service().record_detail,payload.projectId,payload.scope,payload.recordId,True)
+    return {**result,'notice':'Removes this memory and its history. Project files remain.'}
+
+@router.post('/api/memory/forget')
+async def forget(payload:Forget):
+    return await invoke(service().forget,payload.projectId,payload.scope,payload.recordId)
+
+@router.post('/api/memory/skill')
+async def skill(payload:Skill):
+    memory=service()
+    if payload.skillId not in {s['id'] for s in skills.registry()}:raise HTTPException(422,'Unknown skill')
+    with memory.lock,memory.db() as db:db.execute('INSERT OR REPLACE INTO skill_settings VALUES (?,?)',(payload.skillId,int(payload.enabled)))
+    return {'enabled':payload.enabled}
+
+@router.post('/api/pricing/aws-s3')
+async def price(payload:Price):
+    try:return await asyncio.to_thread(aws_s3,payload.region)
+    except Exception:raise HTTPException(503,'AWS storage pricing is unavailable or the region is not supported. No price was invented.')
+
+@router.post('/api/pricing/storage')
+async def storage(payload:Price):
+    try:return await asyncio.to_thread(storage_quote,payload.provider,payload.region)
+    except Exception:raise HTTPException(503,'The exact provider/region price could not be verified. No rate was invented.')
+
+
+class LambdaPrice(Target):
+    region:str=Field(max_length=40)
+    architecture:Literal['x86_64','arm64']='x86_64'
+
+@router.post('/api/pricing/lambda')
+async def lambda_price(payload:LambdaPrice):
+    try:return await asyncio.to_thread(lambda_quote,payload.region,payload.architecture)
+    except Exception:raise HTTPException(503,'The regional Lambda price is unavailable. Retry pricing; no rate was invented.')
+
+
+class GooglePrice(Target):
+    service:Literal['cloud-run','cloud-sql']
+    region:str=Field(default='',max_length=40)
+    planningReference:StrictBool=False
+
+@router.post('/api/pricing/google')
+async def google_price(payload:GooglePrice):
+    try:return await asyncio.to_thread(google_public_quote,payload.service,payload.region,payload.planningReference)
+    except ValueError as error:raise HTTPException(422,str(error)) from None
+    except Exception:raise HTTPException(503,'Google pricing could not be verified. Retry pricing.') from None
+
+
+class MemoryPage(Target):
+    scope:Literal['user','project','knowledge']='project'
+    status:Literal['active','superseded','quarantined','all']='active'
+    query:str=Field(default='',max_length=200)
+    cursor:str|None=Field(default=None,max_length=500)
+    limit:int=Field(default=50,ge=1,le=100,strict=True)
+
+class ProfileName(Strict):
+    name:str=Field(min_length=1,max_length=80)
+
+@router.post('/api/memory/records')
+async def memory_records(payload:MemoryPage):
+    return await invoke(service().browse,payload.projectId,payload.scope,status=payload.status,query=payload.query,cursor=payload.cursor,limit=payload.limit)
+
+@router.post('/api/memory/record')
+async def memory_record(payload:Forget):
+    return await invoke(service().record_detail,payload.projectId,payload.scope,payload.recordId)
+
+@router.post('/api/memory/user-profile')
+async def user_profile(payload:ProfileName):
+    return await invoke(service().rename_profile,payload.name)
+
+
+class ContextRequest(Target):
+    query:str=Field(min_length=1,max_length=4000)
+
+@router.post('/api/memory/context')
+async def memory_context(payload:ContextRequest):
+    memory=service()
+    records,status=await invoke(memory.recall,payload.projectId,payload.query)
+    return {'records':records,'status':status,'userId':memory.owner,'projectId':payload.projectId,'boundary':'retrieval_only'}
+
+
+@router.post('/api/memory/overview')
+async def memory_overview(payload:Target):
+    memory=service();result=await invoke(memory.overview,payload.projectId)
+    result['skills']=skills.public(skills.catalogue(memory,payload.projectId))
+    return result

package/server/memory_service.py

@@ -0,0 +1,306 @@
+from .settings import setting, home as product_home
+"""AtMem AI Architect's authenticated single-user scope policy over the real AtMem core SDK.
+
+Application queue/receipts live in state.sqlite; memory and supersession live in AtMem.
+No unfiltered dashboard, shared ~/.atmem store, or model-selected subject is exposed.
+"""
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import sqlite3
+import subprocess
+import threading
+import uuid
+from contextlib import contextmanager
+from datetime import datetime, timezone
+
+ROOT = Path(__file__).resolve().parent.parent
+SECRET_KEY = re.compile(r'^(password|secret|api_?key|access_?key|token|client_?secret)$', re.I)
+SECRET_VALUE = re.compile(r'AKIA[0-9A-Z]{16}|sk-(?:ant-)?[A-Za-z0-9_-]{20,}|ghp_[A-Za-z0-9]{36}|AIza[\w-]{35}|-----BEGIN .*PRIVATE KEY-----')
+
+
+def safe(value):
+    if isinstance(value, str):
+        return not SECRET_VALUE.search(value)
+    if isinstance(value, list):
+        return all(safe(v) for v in value)
+    if isinstance(value, dict):
+        return all(not (SECRET_KEY.match(k) and v) and safe(v) for k, v in value.items())
+    return True
+
+
+def digest(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+
+
+def timestamp():
+    return datetime.now(timezone.utc).isoformat()
+
+
+class MemoryService:
+    def __init__(self, home=None, worker=None):
+        self.home = Path(home or product_home()) / 'memory'
+        self.home.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self.worker = str(worker or setting('MEMORY_PYTHON') or ROOT / '.memory-venv' / ('Scripts/python.exe' if os.name == 'nt' else 'bin/python'))
+        self.lock = threading.RLock()
+        self.error = None
+        with self.db() as db:
+            db.executescript('''
+              CREATE TABLE IF NOT EXISTS identity (id TEXT PRIMARY KEY);
+              CREATE TABLE IF NOT EXISTS profiles (id TEXT PRIMARY KEY,name TEXT NOT NULL);
+              CREATE TABLE IF NOT EXISTS settings (project TEXT PRIMARY KEY, enabled INTEGER NOT NULL DEFAULT 1);
+              CREATE TABLE IF NOT EXISTS snapshots (project TEXT PRIMARY KEY, revision INTEGER, entities TEXT, digest TEXT);
+              CREATE TABLE IF NOT EXISTS queue (seq INTEGER PRIMARY KEY AUTOINCREMENT, event_id TEXT UNIQUE, project TEXT, scope TEXT, key TEXT, text TEXT, source TEXT, state TEXT, created TEXT);
+              CREATE TABLE IF NOT EXISTS activity (id TEXT PRIMARY KEY, project TEXT, created TEXT, payload TEXT);
+              CREATE TABLE IF NOT EXISTS skill_settings (id TEXT PRIMARY KEY, enabled INTEGER);
+            ''')
+            row = db.execute('SELECT id FROM identity').fetchone()
+            if 'reason' not in {r[1] for r in db.execute('PRAGMA table_info(queue)')}:
+                db.execute("ALTER TABLE queue ADD COLUMN reason TEXT DEFAULT ''")
+            self.owner = row[0] if row else str(uuid.uuid4())
+            if not row:
+                db.execute('INSERT INTO identity VALUES (?)', (self.owner,))
+            db.execute("INSERT OR IGNORE INTO profiles VALUES (?,?)",(self.owner,'Default profile'))
+
+    @contextmanager
+    def db(self):
+        db = sqlite3.connect(self.home / 'state.sqlite', timeout=15)
+        db.execute('PRAGMA secure_delete=ON')
+        try:
+            with db:
+                yield db
+        finally:
+            db.close()
+
+    def project(self, project):
+        if not isinstance(project, str) or not re.fullmatch(r'[A-Za-z0-9-]{8,64}', project):
+            raise ValueError('Invalid project identity')
+        return project
+
+    def subject(self, scope, project):
+        return 'atforma-' + digest([self.owner, scope, project if scope == 'project' else 'shared'])[:40]
+
+    def enabled(self, project):
+        with self.db() as db:
+            row = db.execute('SELECT enabled FROM settings WHERE project=?', (project,)).fetchone()
+        return not row or bool(row[0])
+
+    def configure(self, project, enabled):
+        self.project(project)
+        with self.lock, self.db() as db:
+            db.execute('INSERT OR REPLACE INTO settings VALUES (?,?)', (project, int(enabled)))
+            if not enabled:
+                db.execute("UPDATE queue SET state='cancelled' WHERE project=? AND state='pending'", (project,))
+        return {'enabled': enabled}
+
+    def call(self, operations):
+        operations=[{**op,'owner':self.owner,'actor':'user:'+self.owner if (op.get('subject')==self.subject('user','') or op.get('action')=='forget') else 'atmem-project-sync','actorType':'user' if (op.get('subject')==self.subject('user','') or op.get('action')=='forget') else 'project-sync'}for op in operations]
+        result = subprocess.run([self.worker, '-I', str(ROOT / 'server/memory_worker.py')],
+            input=json.dumps({'database': str(self.home / 'memories.db'), 'operations': operations}),
+            text=True, capture_output=True, timeout=25, cwd=str(self.home))
+        try:
+            payload = json.loads(result.stdout)
+        except (ValueError, TypeError):
+            raise RuntimeError('AtMem runtime unavailable; run npm run setup:memory') from None
+        if result.returncode or 'error' in payload:
+            raise RuntimeError('AtMem rejected the operation (' + payload.get('error', 'worker failed') + ')')
+        self.error = None
+        return payload['results']
+
+    def enqueue(self, project, scope, key, text, event_id=None, source=''):
+        if not safe(text) or len(text) > 1900:
+            raise ValueError('Memory content is too long or looks like a credential')
+        event_id = event_id or digest([project, scope, key, text])
+        with self.db() as db:
+            db.execute("INSERT OR IGNORE INTO queue(event_id,project,scope,key,text,source,state,created) VALUES (?,?,?,?,?,?,'pending',?)", (event_id, project, scope, key, text, source, timestamp()))
+
+    def flush(self):
+        with self.lock:
+            with self.db() as db:
+                rows = db.execute("SELECT seq,event_id,project,scope,key,text,source FROM queue WHERE state='pending' ORDER BY seq LIMIT 500").fetchall()
+            if not rows:
+                return True
+            try:
+                # The worker durably receipts each event so a partial batch can replay safely.
+                results = self.call([{'action': 'remember', 'subject': self.subject(scope, project), 'key': key, 'text': text, 'eventId': event, 'source': source} for seq, event, project, scope, key, text, source in rows])
+                with self.db() as db:
+                    for row, result in zip(rows, results):
+                        db.execute("UPDATE queue SET state=?,reason=?,text='',source='' WHERE seq=?", ('rejected' if result.get('refused') else 'synced', json.dumps(result.get('refused',[])), row[0]))
+                return True
+            except (OSError, RuntimeError, subprocess.TimeoutExpired):
+                self.error = 'AtMem unavailable — using this project only; eligible changes queued'
+                return False
+
+    @staticmethod
+    def entities(file):
+        values = {}
+        design = file.get('design') or {}
+        # The editable project already holds the diagram, comments and conversation brief.
+        # Only durable, confirmed facts belong in long-term memory.
+        for category in ('requirements', 'assumptions', 'openQuestions'):
+            for item in file.get(category, [])[:300]:
+                if category != 'requirements' or item.get('source') != 'user' or item.get('priority') != 'must' or str(item.get('id','')).startswith('drv-'):
+                    continue
+                key = str(item.get('id', ''))
+                content = item.get('statement') or item.get('question')
+                if key and content:
+                    values[f'{category}.{key}'] = f'{category} [{key}]: {content}; status: {item.get("status", "recorded")}'[:1800]
+        for item in file.get('discovery', {}).get('facts', [])[:300]:
+            if isinstance(item, dict) and item.get('name') == 'budget.per_month' and not item.get('conflictsWith'):
+                name = str(item['name'])
+                values['fact.' + name] = f'Project fact {name}: {item.get("value")} {item.get("unit", "")}; stated {item.get("madeAt", "unknown")}' + ('; unresolved conflict: confirm with user' if item.get('conflictsWith') else '')
+        decisions = file.get('decisions', [])
+        for item in decisions[:200]:
+            if item.get('status') != 'Accepted':
+                continue
+            subject = str(item.get('subject') or item.get('id') or 'decision')
+            if subject.startswith('design.'):
+                continue
+            values['decision.' + subject] = f'Project decision {subject}: {item.get("decision") or item.get("title", "")}; status: {item.get("status", "Proposed")}; reason: {item.get("reason") or item.get("rationale") or "not recorded"}'[:1800]
+        return values
+
+    def sync(self, project, file):
+        self.project(project)
+        if not isinstance(file, dict) or file.get('format') not in {'atmem.ai-architect.project','atforma.project'} or file.get('meta', {}).get('id') != project or not safe(file):
+            raise ValueError('Invalid project snapshot or credential-bearing data')
+        revision = file.get('meta', {}).get('revision')
+        if not isinstance(revision, int) or revision < 1:
+            raise ValueError('Invalid project revision')
+        with self.lock:
+            if not self.enabled(project):
+                return {'enabled': False, 'status': 'disabled'}
+            entities = self.entities(file)
+            with self.db() as db:
+                old = db.execute('SELECT revision,entities,digest FROM snapshots WHERE project=?', (project,)).fetchone()
+            if old and revision < old[0]:
+                return {'status': 'conflict', 'detail': 'Older project revision; memory was not changed'}
+            previous = json.loads(old[1]) if old else {}
+            change_id = str(uuid.uuid4())
+            with self.db() as db:
+                # Snapshot update and outbox insertion are one transaction: no lost change on crash.
+                for key in previous.keys() | entities.keys():
+                    text = entities.get(key, f'{key} was removed from this project; do not treat the earlier value as current.')
+                    if previous.get(key) == entities.get(key):
+                        continue
+                    db.execute("INSERT INTO queue(event_id,project,scope,key,text,source,state,created) VALUES (?,?,?,?,?,?,'pending',?)", (digest([change_id,key]), project, 'project', key, text, 'project snapshot r' + str(revision), timestamp()))
+                db.execute('INSERT OR REPLACE INTO snapshots VALUES (?,?,?,?)', (project, revision, json.dumps(entities), digest(file)))
+            self.flush()
+            return self.status(project)
+
+    def status(self, project):
+        with self.db() as db:
+            counts = dict(db.execute('SELECT state,count(*) FROM queue WHERE project=? GROUP BY state', (project,)).fetchall())
+        return {'enabled': self.enabled(project), 'status': 'disabled' if not self.enabled(project) else 'unavailable' if self.error else 'ready', 'pending': counts.get('pending', 0), 'rejected': counts.get('rejected', 0), 'engine': 'AtMem 2.3.10 core SDK', 'policy': 'AtMem AI Architect single-user scope and opt-out policy', 'detail': self.error}
+
+    def profile(self, project, field, value):
+        if field not in {'explanation', 'experience', 'iac', 'preferences'} or not value.strip() or len(value) > 1000:
+            raise ValueError('Choose a profile field and enter up to 1,000 characters')
+        with self.lock:
+            if not self.enabled(project):
+                raise ValueError('Memory is disabled for this project')
+            # User presses Remember; these are confirmed preferences, not model inferences.
+            self.enqueue(project, 'user', 'profile.' + field, f'User-confirmed {field}: {value.strip()}', event_id=str(uuid.uuid4()))
+            self.flush()
+            return self.status(project)
+
+    def overview(self,project):
+        from .memory_context import describe
+        self.project(project)
+        with self.lock,self.db()as db:
+            activity=[{'id':row[0],'createdAt':row[1],**json.loads(row[2])}for row in db.execute('SELECT id,created,payload FROM activity WHERE project=? ORDER BY created DESC LIMIT 20',(project,))]
+        return {**self.status(project),'activity':activity,'userProfile':self.user_profile(),'contextProviders':describe()}
+
+    def inspect(self, project):
+        from .memory_context import describe
+        self.project(project)
+        with self.lock:
+            if self.enabled(project):
+                self.flush()
+            subjects = [self.subject('user', project), self.subject('project', project), self.subject('knowledge', project)]
+            try:
+                results = self.call([{'action': 'page', 'subject': s,'status':'all','limit':50} for s in subjects])
+                records = [page['records'] for page in results]
+            except (OSError, RuntimeError, subprocess.TimeoutExpired):
+                self.error = 'AtMem unavailable — using this project only; eligible changes queued'
+                records = [[], [], []]
+            with self.db() as db:
+                activity = [{'id': r[0], 'createdAt': r[1], **json.loads(r[2])} for r in db.execute('SELECT id,created,payload FROM activity WHERE project=? ORDER BY created DESC LIMIT 20', (project,))]
+                events = [{'key':r[0],'status':r[1],'reason':r[2],'createdAt':r[3]} for r in db.execute("SELECT key,state,reason,created FROM queue WHERE project=? AND state IN ('pending','rejected') ORDER BY seq DESC LIMIT 20",(project,))]
+            return {**self.status(project), 'profile': records[0], 'project': records[1], 'knowledge': records[2], 'activity': activity, 'events':events,'userProfile':self.user_profile(),'contextProviders':describe()}
+
+    def user_profile(self):
+        with self.db()as db:name=db.execute('SELECT name FROM profiles WHERE id=?',(self.owner,)).fetchone()[0]
+        return {'id':self.owner,'name':name,'kind':'local','identitySource':'local-installation'}
+
+    def rename_profile(self,name):
+        if not isinstance(name,str)or not name.strip()or len(name)>80:raise ValueError('Enter a profile name up to 80 characters')
+        with self.lock,self.db()as db:db.execute('UPDATE profiles SET name=? WHERE id=?',(name.strip(),self.owner))
+        return self.user_profile()
+
+    def browse(self,project,scope='project',**options):
+        self.project(project)
+        if scope not in {'user','project','knowledge'}:raise ValueError('Invalid memory scope')
+        with self.lock:return self.call([{'action':'page','subject':self.subject(scope,project),**options}])[0]
+
+    def record_detail(self,project,scope,record_id,preview=False):
+        self.project(project)
+        if scope not in {'user','project'}:raise ValueError('Invalid memory scope')
+        with self.lock:return self.call([{'action':'forget-preview'if preview else 'record','subject':self.subject(scope,project),'recordId':record_id}])[0]
+
+    def forget(self, project, scope, record_id):
+        if scope not in {'user', 'project'}:
+            raise ValueError('Invalid memory scope')
+        with self.lock:
+            result = self.call([{'action': 'forget', 'subject': self.subject(scope, project), 'recordId': record_id}])[0]
+            key = result.pop('key')
+            with self.db() as db:
+                # Remove plaintext outbox copies too, and cancel replay of this exact key.
+                if scope == 'user':
+                    db.execute('DELETE FROM queue WHERE scope=? AND key=?', (scope, key))
+                else:
+                    db.execute('DELETE FROM queue WHERE project=? AND scope=? AND key=?', (project, scope, key))
+            return result
+
+    def recall(self, project, query):
+        self.project(project)
+        with self.lock:
+            if not self.enabled(project):
+                return [], self.status(project)
+            if not self.flush():
+                return [], self.status(project)
+            try:
+                rows = self.call([{'action': 'recall', 'subject': self.subject(s, project), 'query': query, 'limit': 6} for s in ('user', 'project')])
+                context = [{'scope': scope, 'id': r['id'], 'text': r['content'], 'sourceDate': r['created_at'], 'key': r.get('fact_key')} for scope, records in zip(('user','project'), rows) for r in records]
+                from .memory_context import retrieve
+                external,provider_status=retrieve(project,self.owner,query,safe)
+                return context+external,{**self.status(project),'contextProviders':provider_status}
+            except (OSError, RuntimeError, subprocess.TimeoutExpired):
+                self.error = 'AtMem unavailable — using this project only; eligible changes queued'
+                return [], self.status(project)
+
+    def record_turn(self, project, payload):
+        payload={**payload,'userId':self.owner,'actor':'atmem-architect','actorType':'agent'}
+        ident = str(uuid.uuid4())
+        with self.lock, self.db() as db:
+            db.execute('INSERT INTO activity VALUES (?,?,?,?)', (ident, project, timestamp(), json.dumps(payload)))
+            db.execute('DELETE FROM activity WHERE project=? AND id NOT IN (SELECT id FROM activity WHERE project=? ORDER BY created DESC LIMIT 100)', (project, project))
+        if self.enabled(project) and payload.get('recordIds'):
+            try:
+                self.call([{'action': 'log', 'subject': self.subject('project', project), 'eventType': 'atforma.turn', 'payload': payload}])
+            except (OSError, RuntimeError, subprocess.TimeoutExpired):
+                pass
+        return ident
+
+
+_instance = None
+_instance_home = None
+_guard = threading.Lock()
+def service():
+    global _instance, _instance_home
+    home = str(product_home())
+    with _guard:
+        if _instance is None or _instance_home != home:
+            _instance, _instance_home = MemoryService(home), home
+    return _instance

package/server/memory_worker.py

@@ -0,0 +1,129 @@
+"""Isolated pinned AtMem SDK process. JSON over stdio; no model/cloud tools."""
+import json
+import sys
+import sqlite3
+import base64
+import re
+from importlib.metadata import version
+from atmem import Memory
+
+
+def public_record(record, owner=None, memory=None):
+    episode=memory.store.get_episode(record['subject_id'],record['episode_id'])if memory and record.get('episode_id')else None
+    raw=(episode or {}).get('raw') or record.get('raw') or {}
+    return {**{key:record.get(key)for key in ('id','content','status','fact_key','created_at','updated_at','supersedes_id','source_type')},
+            'governance':{'userId':raw.get('user_id'), 'actor':raw.get('actor'), 'actorType':raw.get('actor_type'),
+                          'source':raw.get('source_url') or raw.get('interpreter'), 'ownerUserId':owner}}
+
+
+def page_records(memory,subject,op):
+    # Pinned SDK adapter: use its policy-aware connection, never reopen the database.
+    from atmem.store.sqlite import _record_from_row
+    db=memory.store._conn
+    limit=max(1,min(int(op.get('limit',50)),100));query=str(op.get('query','')).strip()[:200]
+    status=op.get('status','active')
+    statuses=('active','superseded','quarantined') if status=='all' else (status,)
+    if any(value not in {'active','superseded','quarantined'}for value in statuses):raise ValueError('Invalid memory status')
+    before=None
+    if op.get('cursor'):
+        before=json.loads(base64.urlsafe_b64decode(op['cursor']).decode())
+        if not isinstance(before,list)or len(before)!=2 or any(not isinstance(v,str)or len(v)>100 for v in before):raise ValueError('Invalid page cursor')
+    candidates=[];total=0
+    for selected in statuses:
+        clauses=['subject_id=?','status=?'];args=[subject,selected]
+        if query:
+            if query.startswith('rec_'):
+                clauses.append('id=?');args.append(query)
+            else:
+                terms=re.findall(r'[^\W_]+',query,flags=re.UNICODE)[:12]
+                if not terms:raise ValueError('Enter a search word or record ID')
+                if not memory.store._fts_enabled:raise ValueError('Indexed search is unavailable for this store')
+                expression=' AND '.join('"'+word.replace('"','')+'"'for word in terms)
+                clauses.append('id IN (SELECT record_id FROM records_fts WHERE records_fts MATCH ? AND subject_id=?)')
+                args.extend([expression,subject])
+        where=' AND '.join(clauses)
+        total+=db.execute('SELECT COUNT(*) FROM records WHERE '+where,args).fetchone()[0]
+        if before:where+=' AND (created_at,id)<(?,?)';args.extend(before)
+        rows=db.execute('SELECT * FROM records WHERE '+where+' ORDER BY created_at DESC,id DESC LIMIT ?',(*args,limit+1)).fetchall()
+        candidates.extend(_record_from_row(row)for row in rows)
+    candidates.sort(key=lambda row:(row['created_at'],row['id']),reverse=True)
+    more=len(candidates)>limit;rows=candidates[:limit]
+    cursor=base64.urlsafe_b64encode(json.dumps([rows[-1]['created_at'],rows[-1]['id']]).encode()).decode()if more and rows else None
+    return {'records':[public_record(row,op.get('owner'),memory)for row in rows],'total':total,'hasMore':more,'nextCursor':cursor,'limit':limit}
+
+
+def keyed_records(memory,subject,record_id,limit=10001):
+    record=memory.store.get_record(subject,record_id)
+    if not record or record['status']=='tombstoned':raise ValueError('Memory is unavailable in this scope')
+    if not record.get('fact_key'):return record,[record]
+    from atmem.store.sqlite import _record_from_row
+    rows=memory.store._conn.execute("SELECT * FROM records WHERE subject_id=? AND fact_key IS ? AND status IN ('active','superseded','quarantined') ORDER BY created_at DESC,id DESC LIMIT ?",(subject,record.get('fact_key'),limit)).fetchall()
+    return record,[_record_from_row(row)for row in rows]
+
+
+def run(payload):
+    if version('atmem') != '2.3.10':
+        raise RuntimeError('AtMem AI Architect requires the tested AtMem 2.3.10 runtime')
+    memory = Memory(payload['database'], auto_vectors=False)
+    receipts = sqlite3.connect(payload['database'] + '.receipts.sqlite')
+    receipts.execute('CREATE TABLE IF NOT EXISTS receipts (id TEXT PRIMARY KEY, result TEXT)')
+    results = []
+    try:
+        for op in payload['operations']:
+            subject = op['subject']
+            action = op['action']
+            if action == 'remember':
+                previous = receipts.execute('SELECT result FROM receipts WHERE id=?', (op['eventId'],)).fetchone()
+                if previous:
+                    results.append(json.loads(previous[0]))
+                    continue
+                value = memory.remember(subject, message=op['text'], source_type='user_message',
+                    interpreted_fact=op['text'], interpreted_fact_key=op['key'], actor=op.get('actor','atforma'),
+                    raw={'interpreter': 'atforma-project-event-v1', 'event_id': op['eventId'], 'source_url': op.get('source', ''), 'user_id':op.get('owner'), 'actor':op.get('actor'), 'actor_type':op.get('actorType')})
+                receipt = {'refused': value.get('refused', []), 'ids': [r['id'] for r in value.get('records', [])] + value.get('duplicate_ids', [])}
+                receipts.execute('INSERT INTO receipts VALUES (?,?)', (op['eventId'], json.dumps(receipt)))
+                receipts.commit()
+                results.append(receipt)
+            elif action == 'recall':
+                results.append(memory.recall(subject, op['query'], limit=op.get('limit', 6)))
+            elif action == 'page':
+                results.append(page_records(memory,subject,op))
+            elif action == 'record':
+                record=memory.store.get_record(subject,op['recordId'])
+                if not record or record['status']=='tombstoned':raise ValueError('Record unavailable in this scope')
+                audit=memory.store._conn.execute('SELECT actor,event_type,created_at FROM audit_log WHERE subject_id=? AND record_id=? ORDER BY created_at DESC,sequence DESC LIMIT 50',(subject,op['recordId'])).fetchall()
+                results.append({'record':public_record(record,op.get('owner'),memory),'audit':[dict(row)for row in audit]})
+            elif action == 'forget-preview':
+                record,rows=keyed_records(memory,subject,op['recordId'],101)
+                total=memory.store._conn.execute("SELECT COUNT(*) FROM records WHERE subject_id=? AND fact_key IS ? AND status!='tombstoned'",(subject,record.get('fact_key'))).fetchone()[0]if record.get('fact_key')else 1
+                results.append({'records':[public_record(row,op.get('owner'),memory)for row in rows[:100]],'total':total})
+            elif action == 'list':
+                results.append(memory.list(subject, include_inactive=True))
+            elif action == 'forget':
+                # Forget the entire keyed preference history so old values cannot resurface.
+                record,records=keyed_records(memory,subject,op['recordId'])
+                if len(records)>10000:raise ValueError('History exceeds the synchronous removal limit; no records were removed')
+                deletion_receipts = []
+                for r in records:
+                    deletion_receipts.append(memory.forget_record(subject,r['id'],actor=op.get('actor','user'))['receipt'])
+                results.append({'deleted': True, 'receipts': deletion_receipts, 'key': record.get('fact_key')})
+            elif action == 'audit':
+                report = memory.audit(subject)
+                results.append({'valid': report['audit_chain_valid'], 'events': report['audit_log'][-40:]})
+            elif action == 'log':
+                results.append(memory.log_action(subject, op['eventType'], op['payload'], actor='atmem-architect:'+op.get('owner','unknown')))
+            else:
+                raise ValueError('Unknown memory operation')
+        return {'version': version('atmem'), 'results': results}
+    finally:
+        memory.close()
+        receipts.close()
+
+
+if __name__ == '__main__':
+    try:
+        print(json.dumps(run(json.load(sys.stdin))))
+    except Exception as exc:
+        # No text/credentials from an exception cross this process boundary.
+        print(json.dumps({'error': type(exc).__name__}))
+        sys.exit(1)