feat: merge feat/tenure-borrowed-beliefs into develop

Author: escapeboy

app/Domain/Memory/Actions/ExtractAndStoreMemoriesAction.php

@@ -5,7 +5,10 @@
 use App\Domain\Agent\Models\Agent;
 use App\Domain\Agent\Models\AgentExecution;
 use App\Domain\Experiment\Models\Experiment;
+use App\Domain\Memory\Enums\MemoryBeliefStatus;
+use App\Domain\Memory\Enums\MemoryBeliefType;
 use App\Domain\Memory\Enums\MemoryCategory;
+use App\Domain\Memory\Enums\MemoryPreferenceSubtype;
 use App\Domain\Memory\Enums\MemoryTier;
 use App\Domain\Shared\Models\Team;
 use App\Infrastructure\AI\Contracts\AiGatewayInterface;
@@ -45,6 +48,10 @@ class ExtractAndStoreMemoriesAction
       "fact": "concise, durable statement",
       "confidence": 0.85,
       "category": "knowledge",
+      "belief_type": "preference",
+      "preference_subtype": "style",
+      "why_it_matters": "actionable directive: how a future run should behave because of this fact",
+      "domain": "domain:code",
       "tags": ["capability"]
     }
   ]
@@ -57,6 +64,20 @@ class ExtractAndStoreMemoriesAction
   - context: situational context, recent events, current state
   - behavior: working patterns, process preferences, habits
   - goal: objectives, targets, desired outcomes
+belief_type must be exactly one of: preference, decision, entity, relation, open_question
+  - preference: how the user/agent works and communicates
+  - decision: a commitment future runs must respect
+  - entity: a named thing in the user's world (a service, team, system)
+  - relation: a connection between entities (a dependency, ownership)
+  - open_question: something being worked through, not yet decided
+preference_subtype is OPTIONAL and only valid when belief_type is "preference":
+  - expertise: depth calibration — how much to explain
+  - style: communication tone, format, voice
+why_it_matters: a single actionable directive, not a restatement of the fact.
+  Write "shapes all code examples toward TypeScript strict mode" — not "uses TypeScript".
+domain: a scope tag so the belief only surfaces in matching sessions. Use
+  "domain:code", "domain:writing", "domain:ops", etc., or "user:universal" when
+  the fact applies everywhere. Omit if unsure.
 Tags must be one or more of: capability, constraint, preference, pattern, domain, tooling
 PROMPT;
 
@@ -145,6 +166,19 @@ public function execute(string $agentId, string $teamId, string $executionId, ?s
                 $categoryValue = $item['category'] ?? null;
                 $category = $categoryValue ? MemoryCategory::tryFrom($categoryValue) : null;
 
+                $beliefType = isset($item['belief_type']) && is_string($item['belief_type'])
+                    ? MemoryBeliefType::tryFrom($item['belief_type'])
+                    : null;
+                $preferenceSubtype = isset($item['preference_subtype']) && is_string($item['preference_subtype'])
+                    ? MemoryPreferenceSubtype::tryFrom($item['preference_subtype'])
+                    : null;
+                $whyItMatters = isset($item['why_it_matters']) && is_string($item['why_it_matters'])
+                    ? trim($item['why_it_matters'])
+                    : null;
+                $domain = isset($item['domain']) && is_string($item['domain']) && $item['domain'] !== ''
+                    ? $item['domain']
+                    : null;
+
                 if ($fact === '' || $confidence < self::MIN_CONFIDENCE) {
                     continue;
                 }
@@ -162,6 +196,13 @@ public function execute(string $agentId, string $teamId, string $executionId, ?s
                     tier: MemoryTier::Proposed,
                     proposedBy: "agent:{$agentId}",
                     category: $category,
+                    beliefType: $beliefType,
+                    preferenceSubtype: $preferenceSubtype,
+                    whyItMatters: $whyItMatters !== '' ? $whyItMatters : null,
+                    // Extracted facts are derived, not explicitly stated — they
+                    // await confirmation before becoming active beliefs.
+                    beliefStatus: MemoryBeliefStatus::Inferred,
+                    domain: $domain,
                 );
 
                 $stored++;

app/Domain/Memory/Actions/RetrieveRelevantMemoriesAction.php

@@ -33,6 +33,7 @@ public function execute(
         float $minConfidence = 0.3,
         ?array $tags = null,
         ?string $topic = null,
+        ?string $domain = null,
     ): Collection {
         if (! config('memory.enabled', true)) {
             return collect();
@@ -73,6 +74,8 @@ public function execute(
                 ->where('confidence', '>=', $minConfidence)
                 // Exclude rejected proposals — keep NULL (legacy) and approved.
                 ->where(fn ($q) => $q->whereNull('proposal_status')->orWhere('proposal_status', '!=', 'rejected'))
+                // Superseded beliefs are retained for audit but never injected.
+                ->where(fn ($q) => $q->whereNull('belief_status')->orWhere('belief_status', '!=', 'superseded'))
                 ->orderByDesc('composite_score');
 
             // Topic namespace pre-filter: narrows the candidate set before the pgvector scan.
@@ -81,6 +84,13 @@ public function execute(
                 $builder->where('topic', $topic);
             }
 
+            // Domain scope: a hard filter applied after scoring. A belief scoped
+            // to one domain (e.g. domain:code) never surfaces in another domain's
+            // session. NULL-domain beliefs are universal and always eligible.
+            if ($domain !== null) {
+                $builder->where(fn ($q) => $q->where('domain', $domain)->orWhereNull('domain'));
+            }
+
             // Tag-based filtering (opt-in: only applied when tags are passed)
             if (! empty($tags)) {
                 $this->applyTagFilter($builder, $tags);

app/Domain/Memory/Actions/StoreMemoryAction.php

@@ -2,7 +2,10 @@
 
 namespace App\Domain\Memory\Actions;
 
+use App\Domain\Memory\Enums\MemoryBeliefStatus;
+use App\Domain\Memory\Enums\MemoryBeliefType;
 use App\Domain\Memory\Enums\MemoryCategory;
+use App\Domain\Memory\Enums\MemoryPreferenceSubtype;
 use App\Domain\Memory\Enums\MemoryTier;
 use App\Domain\Memory\Enums\MemoryVisibility;
 use App\Domain\Memory\Enums\WriteGateDecision;
@@ -55,6 +58,11 @@ public function execute(
         ?MemoryCategory $category = null,
         ?string $topic = null,
         ?string $documentContext = null,
+        ?MemoryBeliefType $beliefType = null,
+        ?MemoryPreferenceSubtype $preferenceSubtype = null,
+        ?string $whyItMatters = null,
+        MemoryBeliefStatus $beliefStatus = MemoryBeliefStatus::Active,
+        ?string $domain = null,
     ): array {
         if (! config('memory.enabled', true)) {
             return [];
@@ -76,6 +84,7 @@ public function execute(
                     $teamId, $agentId, $chunk, $sourceType,
                     $projectId, $sourceId, $metadata, $confidence,
                     $importance, $tags, $visibility, $tier, $proposedBy, $category, $topic,
+                    $beliefType, $preferenceSubtype, $whyItMatters, $beliefStatus, $domain,
                 );
 
                 if ($memory) {
@@ -121,6 +130,11 @@ private function storeChunk(
         ?string $proposedBy = null,
         ?MemoryCategory $category = null,
         ?string $topic = null,
+        ?MemoryBeliefType $beliefType = null,
+        ?MemoryPreferenceSubtype $preferenceSubtype = null,
+        ?string $whyItMatters = null,
+        MemoryBeliefStatus $beliefStatus = MemoryBeliefStatus::Active,
+        ?string $domain = null,
     ): ?Memory {
         $contentHash = hash('sha256', mb_strtolower(trim($chunk)));
         $embedding = $this->generateEmbedding($chunk, $teamId);
@@ -150,6 +164,7 @@ private function storeChunk(
                 $teamId, $agentId, $chunk, $embedding, $contentHash,
                 $sourceType, $projectId, $sourceId, $metadata,
                 $confidence, $importance, $tags, $visibility, $tier, $proposedBy, $category, $topic,
+                $beliefType, $preferenceSubtype, $whyItMatters, $beliefStatus, $domain,
             ),
         };
     }
@@ -297,7 +312,17 @@ private function handleAdd(
         ?string $proposedBy = null,
         ?MemoryCategory $category = null,
         ?string $topic = null,
+        ?MemoryBeliefType $beliefType = null,
+        ?MemoryPreferenceSubtype $preferenceSubtype = null,
+        ?string $whyItMatters = null,
+        MemoryBeliefStatus $beliefStatus = MemoryBeliefStatus::Active,
+        ?string $domain = null,
     ): Memory {
+        // A preference subtype only applies to Preference beliefs — drop it otherwise.
+        if ($beliefType?->acceptsPreferenceSubtype() !== true) {
+            $preferenceSubtype = null;
+        }
+
         return Memory::create([
             'team_id' => $teamId,
             'agent_id' => $agentId,
@@ -316,6 +341,11 @@ private function handleAdd(
             'category' => $category,
             'topic' => $topic,
             'proposed_by' => $proposedBy,
+            'belief_type' => $beliefType,
+            'preference_subtype' => $preferenceSubtype,
+            'why_it_matters' => $whyItMatters,
+            'belief_status' => $beliefStatus,
+            'domain' => $domain,
         ]);
     }
 

app/Domain/Memory/Enums/MemoryBeliefStatus.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Domain\Memory\Enums;
+
+/**
+ * Belief lifecycle status (Tenure-inspired).
+ *
+ * Runs parallel to the existing tier/proposal_status workflow. Where
+ * proposal_status tracks human review of agent-proposed memories, belief
+ * status tracks the epistemic confidence in the fact itself.
+ *
+ *   active      → explicitly stated or decided
+ *   inferred    → derived without an explicit statement; awaits confirmation
+ *   exploratory → being considered but not committed
+ *   superseded  → replaced by a newer belief; retained for audit, never injected
+ */
+enum MemoryBeliefStatus: string
+{
+    case Active = 'active';
+    case Inferred = 'inferred';
+    case Exploratory = 'exploratory';
+    case Superseded = 'superseded';
+
+    /** Whether a belief in this status may be injected into agent context. */
+    public function isInjectable(): bool
+    {
+        return $this !== self::Superseded;
+    }
+}

app/Domain/Memory/Enums/MemoryBeliefType.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Domain\Memory\Enums;
+
+/**
+ * Structured belief taxonomy (Tenure-inspired).
+ *
+ * Sits alongside the existing {@see MemoryCategory} taxonomy. Where category
+ * describes the memory hall a record lives in, belief type describes the
+ * epistemic shape of the fact: is it a preference, a committed decision, a
+ * named thing, a link between things, or an unresolved question.
+ *
+ *   preference     → how the user/agent works and communicates
+ *   decision       → a commitment future runs must respect
+ *   entity         → a named thing in the user's world
+ *   relation       → a connection between entities
+ *   open_question  → something actively being worked through, not yet decided
+ */
+enum MemoryBeliefType: string
+{
+    case Preference = 'preference';
+    case Decision = 'decision';
+    case Entity = 'entity';
+    case Relation = 'relation';
+    case OpenQuestion = 'open_question';
+
+    /** Whether this belief type accepts a {@see MemoryPreferenceSubtype}. */
+    public function acceptsPreferenceSubtype(): bool
+    {
+        return $this === self::Preference;
+    }
+}

app/Domain/Memory/Enums/MemoryPreferenceSubtype.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace App\Domain\Memory\Enums;
+
+/**
+ * Optional subtype for {@see MemoryBeliefType::Preference} beliefs.
+ *
+ *   expertise → depth calibration: how much the agent should explain
+ *   style     → communication patterns: tone, format, voice
+ */
+enum MemoryPreferenceSubtype: string
+{
+    case Expertise = 'expertise';
+    case Style = 'style';
+}

app/Domain/Memory/Models/Memory.php

@@ -3,7 +3,10 @@
 namespace App\Domain\Memory\Models;
 
 use App\Domain\Agent\Models\Agent;
+use App\Domain\Memory\Enums\MemoryBeliefStatus;
+use App\Domain\Memory\Enums\MemoryBeliefType;
 use App\Domain\Memory\Enums\MemoryCategory;
+use App\Domain\Memory\Enums\MemoryPreferenceSubtype;
 use App\Domain\Memory\Enums\MemoryTier;
 use App\Domain\Memory\Enums\MemoryVisibility;
 use App\Domain\Project\Models\Project;
@@ -36,6 +39,11 @@ class Memory extends Model
         'tags',
         'tier',
         'category',
+        'belief_type',
+        'preference_subtype',
+        'why_it_matters',
+        'belief_status',
+        'domain',
         'topic',
         'proposed_by',
         'proposal_status',
@@ -61,6 +69,9 @@ protected function casts(): array
             'visibility' => MemoryVisibility::class,
             'tier' => MemoryTier::class,
             'category' => MemoryCategory::class,
+            'belief_type' => MemoryBeliefType::class,
+            'preference_subtype' => MemoryPreferenceSubtype::class,
+            'belief_status' => MemoryBeliefStatus::class,
         ];
     }
 

app/Http/Controllers/Api/V1/MemoryController.php

@@ -4,6 +4,9 @@
 
 use App\Domain\Memory\Actions\RetrieveRelevantMemoriesAction;
 use App\Domain\Memory\Actions\StoreMemoryAction;
+use App\Domain\Memory\Enums\MemoryBeliefStatus;
+use App\Domain\Memory\Enums\MemoryBeliefType;
+use App\Domain\Memory\Enums\MemoryPreferenceSubtype;
 use App\Domain\Memory\Models\Memory;
 use App\Http\Controllers\Controller;
 use App\Http\Resources\Api\V1\MemoryResource;
@@ -25,6 +28,9 @@ public function index(Request $request): AnonymousResourceCollection
                 AllowedFilter::exact('agent_id'),
                 AllowedFilter::exact('project_id'),
                 AllowedFilter::exact('source_type'),
+                AllowedFilter::exact('belief_type'),
+                AllowedFilter::exact('belief_status'),
+                AllowedFilter::exact('domain'),
                 AllowedFilter::partial('content'),
             )
             ->allowedSorts('created_at', 'confidence')
@@ -51,6 +57,7 @@ public function search(Request $request, RetrieveRelevantMemoriesAction $action)
             'top_k' => ['sometimes', 'integer', 'min:1', 'max:50'],
             'threshold' => ['sometimes', 'numeric', 'min:0', 'max:1'],
             'scope' => ['sometimes', 'in:agent,team,project'],
+            'domain' => ['sometimes', 'nullable', 'string', 'max:64'],
         ]);
 
         $memories = $action->execute(
@@ -61,6 +68,7 @@ public function search(Request $request, RetrieveRelevantMemoriesAction $action)
             threshold: $request->input('threshold'),
             scope: $request->input('scope', $request->has('agent_id') ? 'agent' : 'team'),
             teamId: $request->user()->current_team_id,
+            domain: $request->input('domain'),
         );
 
         return response()->json([
@@ -108,6 +116,11 @@ public function store(Request $request, StoreMemoryAction $action): JsonResponse
             'metadata' => ['sometimes', 'array'],
             'tags' => ['sometimes', 'array'],
             'confidence' => ['sometimes', 'numeric', 'min:0', 'max:1'],
+            'belief_type' => ['sometimes', 'nullable', 'string', 'in:preference,decision,entity,relation,open_question'],
+            'preference_subtype' => ['sometimes', 'nullable', 'string', 'in:expertise,style'],
+            'why_it_matters' => ['sometimes', 'nullable', 'string', 'max:2000'],
+            'belief_status' => ['sometimes', 'string', 'in:active,inferred,exploratory,superseded'],
+            'domain' => ['sometimes', 'nullable', 'string', 'max:64'],
         ]);
 
         $memories = $action->execute(
@@ -120,6 +133,11 @@ public function store(Request $request, StoreMemoryAction $action): JsonResponse
             metadata: $request->input('metadata', []),
             confidence: (float) $request->input('confidence', 1.0),
             tags: $request->input('tags', []),
+            beliefType: MemoryBeliefType::tryFrom((string) $request->input('belief_type')),
+            preferenceSubtype: MemoryPreferenceSubtype::tryFrom((string) $request->input('preference_subtype')),
+            whyItMatters: $request->input('why_it_matters'),
+            beliefStatus: MemoryBeliefStatus::tryFrom((string) $request->input('belief_status', 'active')) ?? MemoryBeliefStatus::Active,
+            domain: $request->input('domain'),
         );
 
         return response()->json([

app/Http/Resources/Api/V1/MemoryResource.php

@@ -19,6 +19,11 @@ public function toArray(Request $request): array
             'metadata' => $this->metadata,
             'tags' => $this->tags,
             'confidence' => $this->confidence,
+            'belief_type' => $this->belief_type?->value,
+            'preference_subtype' => $this->preference_subtype?->value,
+            'why_it_matters' => $this->why_it_matters,
+            'belief_status' => $this->belief_status?->value,
+            'domain' => $this->domain,
             'created_at' => $this->created_at->toISOString(),
             'updated_at' => $this->updated_at->toISOString(),
         ];