Disclaimer best practicies Oracle for Security

libs/agent_framework/docs/LONG_TERM_MEMORY.md

@@ -0,0 +1,11 @@
+# Long-Term Memory
+
+Capacidade nativa do `agent_framework`, isolada por `tenant_id + agent_id + customer_key`.
+
+O runtime carrega e injeta as memórias automaticamente. Os dois templates persistem os fatos após `supervisor_review`. Os agentes individuais não precisam de alteração.
+
+## Teste
+
+```bash
+PYTHONPATH=libs/agent_framework/src python templates/agent_template_backend/scripts/test_long_term_memory.py
+```

libs/agent_framework/docs/LONG_TERM_MEMORY_AUTONOMOUS_EN.md

@@ -0,0 +1,63 @@
+### Long-Term Memory on Oracle Autonomous Database
+
+### Activation
+
+```env
+ENABLE_LONG_TERM_MEMORY=true
+LONG_TERM_MEMORY_PROVIDER=autonomous
+
+ADB_USER=ADMIN
+ADB_PASSWORD=<password>
+ADB_DSN=<autonomous_service_name>
+ADB_WALLET_LOCATION=/path/to/wallet
+ADB_WALLET_PASSWORD=<wallet_password_if_applicable>
+ADB_TABLE_PREFIX=AGENTFW
+
+# Optional. Default: ${ADB_TABLE_PREFIX}_LONG_TERM_MEMORY.
+LONG_TERM_MEMORY_ORACLE_TABLE=AGENTFW_LONG_TERM_MEMORY
+```
+
+`LONG_TERM_MEMORY_PROVIDER=oracle` is also accepted.
+
+### Dependency
+
+```bash
+pip install oracledb
+```
+
+### Schema initialization
+
+On the first operation, the provider automatically creates the table and index. The user configured in `ADB_USER` needs permission to create tables and indexes. If a DBA provisions the schema beforehand, initialization accepts the existing objects.
+
+### Identity and isolation
+
+The logical key consists of:
+
+```text
+tenant_id + agent_id + subject_key + category + memory_key
+```
+
+In the current integration, `subject_key` is derived from `customer_key`.
+
+### Test
+
+1. Start the backend with the `autonomous` provider.
+2. Store facts in session A.
+3. Open session B with the same `customer_key`.
+4. Verify retrieval.
+5. Restart the backend and repeat the query.
+6. Query `AGENTFW_LONG_TERM_MEMORY` in Autonomous Database.
+
+```sql
+SELECT TENANT_ID, AGENT_ID, SUBJECT_KEY, CATEGORY, MEMORY_KEY,
+       MEMORY_VALUE, CONFIDENCE, UPDATED_AT
+FROM AGENTFW_LONG_TERM_MEMORY
+ORDER BY UPDATED_AT DESC;
+```
+
+### Notes
+
+- The provider uses `python-oracledb` in thin mode.
+- Synchronous operations run through `asyncio.to_thread`.
+- A wallet is optional when walletless TLS is configured.
+- SQLite and InMemory remain available for development and testing.

libs/agent_framework/docs/LONG_TERM_MEMORY_AUTONOMOUS_PT.md

@@ -0,0 +1,63 @@
+### Long-Term Memory no Oracle Autonomous Database
+
+### Ativação
+
+```env
+ENABLE_LONG_TERM_MEMORY=true
+LONG_TERM_MEMORY_PROVIDER=autonomous
+
+ADB_USER=ADMIN
+ADB_PASSWORD=<senha>
+ADB_DSN=<service_name_do_autonomous>
+ADB_WALLET_LOCATION=/caminho/para/wallet
+ADB_WALLET_PASSWORD=<senha_wallet_se_aplicavel>
+ADB_TABLE_PREFIX=AGENTFW
+
+# Opcional. O padrão é ${ADB_TABLE_PREFIX}_LONG_TERM_MEMORY.
+LONG_TERM_MEMORY_ORACLE_TABLE=AGENTFW_LONG_TERM_MEMORY
+```
+
+Também é aceito `LONG_TERM_MEMORY_PROVIDER=oracle`.
+
+### Dependência
+
+```bash
+pip install oracledb
+```
+
+### Inicialização do schema
+
+Na primeira operação, o provider cria automaticamente a tabela e o índice. O usuário configurado em `ADB_USER` precisa de permissão para criar tabela e índice. Se o schema for provisionado previamente por DBA, a inicialização reconhece os objetos existentes.
+
+### Identidade e isolamento
+
+A chave lógica é composta por:
+
+```text
+tenant_id + agent_id + subject_key + category + memory_key
+```
+
+Na integração atual, `subject_key` é derivado do `customer_key`.
+
+### Teste
+
+1. Inicie o backend com provider `autonomous`.
+2. Grave fatos na sessão A.
+3. Abra a sessão B com o mesmo `customer_key`.
+4. Confirme a recuperação.
+5. Reinicie o backend e repita a consulta.
+6. Consulte a tabela `AGENTFW_LONG_TERM_MEMORY` no Autonomous Database.
+
+```sql
+SELECT TENANT_ID, AGENT_ID, SUBJECT_KEY, CATEGORY, MEMORY_KEY,
+       MEMORY_VALUE, CONFIDENCE, UPDATED_AT
+FROM AGENTFW_LONG_TERM_MEMORY
+ORDER BY UPDATED_AT DESC;
+```
+
+### Observações
+
+- O provider usa `python-oracledb` em thin mode.
+- As operações síncronas são executadas com `asyncio.to_thread`.
+- Wallet é opcional quando a conexão TLS sem wallet estiver configurada.
+- SQLite e InMemory continuam disponíveis para desenvolvimento e testes.