fix tests and README.md

Author: Your Name

README.md

@@ -48,6 +48,26 @@ This system provides a comprehensive memory management solution for AGI applicat
    - Context applicability
    - Success metrics
 
+### Advanced Features
+
+**Memory Clustering:**
+- Automatic thematic grouping of related memories
+- Emotional signature tracking
+- Cross-cluster relationship mapping
+- Activation pattern analysis
+
+**Worldview Integration:**
+- Belief system modeling with confidence scores
+- Memory filtering based on worldview alignment
+- Identity-core memory cluster identification
+- Adaptive memory importance based on beliefs
+
+**Graph Relationships:**
+- Apache AGE integration for complex memory networks
+- Multi-hop relationship traversal
+- Pattern detection across memory types
+- Causal relationship modeling
+
 ### Key Features
 
 - **Vector Embeddings**: Uses pgvector for similarity-based memory retrieval
@@ -65,9 +85,45 @@ This system provides a comprehensive memory management solution for AGI applicat
   - pg_trgm
   - cube
 
-## Setup
+## Dependencies
+
+### Python Requirements
+- asyncpg>=0.29.0 (PostgreSQL async driver)
+- pytest>=7.4.3 (testing framework)
+- numpy>=1.24.0 (numerical operations)
+- fastapi>=0.104.0 (web framework)
+- pydantic>=2.4.2 (data validation)
+
+### Node.js Requirements  
+- @modelcontextprotocol/sdk (MCP framework)
+- pg (PostgreSQL driver)
+
+### Database Extensions
+- pgvector (vector similarity)
+- AGE (graph database)
+- pg_trgm (text search)
+- btree_gist (indexing)
+- cube (multidimensional indexing)
+
+## Environment Configuration
+
+Copy `.env.local` to `.env` and configure:
 
+```bash
+POSTGRES_DB=agi_db           # Database name
+POSTGRES_USER=agi_user       # Database user
+POSTGRES_PASSWORD=agi_password # Database password
 ```
+
+For MCP server, also set:
+```bash
+POSTGRES_HOST=localhost      # Database host
+POSTGRES_PORT=5432          # Database port
+```
+
+## Setup
+
+```bash
 cp .env.local .env # modify the .env file with your own values
 docker compose up -d
 ```
@@ -81,7 +137,61 @@ This will:
 
 Run the test suite with:
 
-`pytest test.py -v`
+```bash
+pytest test.py -v
+```
+
+## API Reference (MCP Tools)
+
+### Memory Operations
+- `create_memory(type, content, embedding, importance, metadata)` - Create new memories
+- `get_memory(memory_id)` - Retrieve and access specific memory
+- `search_memories_similarity(embedding, limit, threshold)` - Vector similarity search
+- `search_memories_text(query, limit)` - Full-text search
+
+### Cluster Operations  
+- `get_memory_clusters(limit)` - List memory clusters by importance
+- `activate_cluster(cluster_id, context)` - Activate cluster and get memories
+- `create_memory_cluster(name, type, description, keywords)` - Create new cluster
+
+### System Introspection
+- `get_identity_core()` - Retrieve identity model and core clusters
+- `get_worldview()` - Get worldview primitives and beliefs
+- `get_memory_health()` - System health statistics
+- `get_active_themes(days)` - Recently activated themes
+
+## Usage Examples
+
+### Creating Memories
+```python
+# Via MCP tools
+memory = await create_memory(
+    type="episodic",
+    content="User expressed interest in machine learning",
+    embedding=embedding_vector,
+    importance=0.8,
+    metadata={
+        "emotional_valence": 0.6,
+        "context": {"topic": "AI", "user_mood": "curious"}
+    }
+)
+```
+
+### Searching Memories
+```python
+# Similarity search
+similar = await search_memories_similarity(
+    embedding=query_vector,
+    limit=10,
+    threshold=0.7
+)
+
+# Text search
+results = await search_memories_text(
+    query="machine learning concepts",
+    limit=5
+)
+```
 
 ## Database Schema
 
@@ -91,7 +201,7 @@ Run the test suite with:
    - Vector embeddings for similarity search
    - Priority scoring for attention mechanisms
 
-2. **long_term_memory**
+2. **memories**
    - Permanent storage for consolidated memories
    - Links to specific memory type tables
    - Metadata tracking (creation, modification, access)
@@ -103,10 +213,22 @@ Run the test suite with:
 
 ### Memory Type Tables
 Each specialized memory type has its own table with type-specific fields:
-- episodic_memory
-- semantic_memory
-- procedural_memory
-- strategic_memory
+- episodic_memories
+- semantic_memories
+- procedural_memories
+- strategic_memories
+
+### Clustering Tables
+- memory_clusters
+- memory_cluster_members
+- cluster_relationships
+- cluster_activation_history
+
+### Identity and Worldview Tables
+- identity_model
+- worldview_primitives
+- worldview_memory_influences
+- identity_memory_resonance
 
 ### Indexes and Constraints
 - Vector indexes for similarity search
@@ -118,7 +240,7 @@ Each specialized memory type has its own table with type-specific fields:
 ### Memory Retrieval
 ```sql
 -- Find similar memories using vector similarity
-SELECT * FROM long_term_memory
+SELECT * FROM memories
 WHERE embedding <-> query_embedding < threshold
 ORDER BY embedding <-> query_embedding
 LIMIT 10;
@@ -131,6 +253,18 @@ SELECT * FROM ag_catalog.cypher('memory_graph', $$
 $$) as (related agtype);
 ```
 
+## Performance Characteristics
+
+- **Vector Search**: Sub-second similarity queries on 10K+ memories
+- **Memory Storage**: Supports millions of memories with proper indexing
+- **Cluster Operations**: Efficient graph traversal for relationship queries
+- **Maintenance**: Requires periodic consolidation and pruning
+
+### Scaling Considerations
+- Memory consolidation recommended every 4-6 hours
+- Database optimization during off-peak hours
+- Monitor vector index performance with large datasets
+
 ## System Maintenance
 
 The memory system requires three key maintenance processes to function effectively:
@@ -161,6 +295,25 @@ These maintenance tasks can be implemented using:
 
 Choose the scheduling method that best fits your infrastructure and monitoring capabilities. Ensure proper logging and error handling for all maintenance operations.
 
+## Troubleshooting
+
+### Common Issues
+
+**Database Connection Errors:**
+- Ensure PostgreSQL is running: `docker compose ps`
+- Check logs: `docker compose logs db`
+- Verify extensions: Run test suite with `pytest test.py -v`
+
+**Memory Search Performance:**
+- Rebuild vector indexes if queries are slow
+- Check memory_health view for system statistics
+- Consider memory pruning if dataset is very large
+
+**MCP Server Issues:**
+- Verify Node.js dependencies: `npm install`
+- Check database connectivity from MCP server
+- Ensure environment variables are set correctly
+
 ## Usage Guide
 
 ### Memory Interaction Flow
@@ -212,7 +365,7 @@ graph TD
 
 ### Key Integration Points
 
-- Use the API for all memory operations
+- Use the MCP API for all memory operations
 - Implement proper error handling for failed operations
 - Monitor memory usage and system performance
 - Regular backup of critical memories
@@ -234,4 +387,4 @@ This database schema is designed for a single AGI instance. Supporting multiple
 - Separate working memory spaces per AGI
 - Additional access controls and memory ownership
 
-If you need multi-AGI support, consider refactoring the schema to include tenant isolation patterns before implementation. 
+If you need multi-AGI support, consider refactoring the schema to include tenant isolation patterns before implementation.