Cognitive Oracle Nexus - Knowledge Persistence Layer

Cognitive Oracle Nexus serves as a specialized MCP (Model Context Protocol) endpoint dedicated to the logging, indexing, and retrieval of systemic programming anomalies. It exposes interfaces via conventional RESTful endpoints and the proprietary MCP protocol, ensuring seamless interoperability with advanced AI tooling such as Claude Code and Cline interfaces.

Key Capabilities

• Persistent logging and recall of error events alongside full diagnostic contexts
• High-dimensional vector similarity querying powered by ChromaDB
• Dual interfacing: RESTful gateway (FastAPI) and native MCP transport
• Robust security layer utilizing JWT verification via API keys
• Hybrid persistence options: Local file system (ChromaDB) and integrated AWS infrastructure
• Containerized deployment strategy via Docker-compose
• Support for integration with custom command-line utilities

Conceptual Summary

The Oracle Nexus is designed to augment Claude's long-term memory regarding software defects. Upon initiation of an AI coding session, the Nexus service is passively accessible via the MCP framework, requiring no manual inclusion by the user.

Claude will perform the following actions: 1. Archive discovered programming errors and their validated fixes. 2. Execute similarity probes against the knowledge archive when novel issues arise. 3. Systematically cultivate a specialized corpus of fixes tailored to the user's unique coding paradigms.

Installation and Packaging via 'uv'

Prerequisites

• Runtime environment: Python version 3.12 or higher
• Recommended dependency manager: The 'uv' utility

Setup Procedures

Method 1: Direct Installation using 'uv'

The most straightforward method involves immediate installation from the source repository location:

bash

Navigate to the project's root directory

cd /absolute/path/to/oracle_nexus

Execute installation via uv

uv pip install .

Method 2: Editable Mode for Development

For active development workflows requiring immediate reflection of source code changes:

bash

Navigate to the project's root directory

cd /absolute/path/to/oracle_nexus

Install in development/editable mode

uv pip install -e .

Method 3: Staged Package Generation

If the objective is to create a distributable binary artifact:

bash

Ensure execution is from the project root

cd /absolute/path/to/oracle_nexus

Ensure the packaging utility is present

uv pip install build

Generate distribution artifacts

python -m build

The package artifacts (.whl) are located in the dist/ folder

Install the generated wheel file

uv pip install dist/cognitive_oracle_nexus-X.Y.Z-py3-none-any.whl

Method 4: Utilizing the 'uv tool install' Abstraction

This method registers the tool for system-wide or localized execution:

bash

Install globally as an executable tool

cd /absolute/path/to/oracle_nexus uv tool install .

Or install in editable configuration

uv tool install -e .

Validation of Installation

Confirm successful deployment:

bash

Locate the installed binary

which cognitive_oracle_nexus

Query the registered version

cognitive_oracle_nexus version

Integration with Claude Ecosystem

Once installed, link the service to the Claude environment:

bash

Register the service within Claude Code

claude mcp register cognitive_oracle_nexus --launch "cognitive_oracle_nexus"

Review all registered services

claude mcp list

For connecting to a containerized deployment

claude mcp register cognitive_oracle_nexus http://interface_host:5000

Operational Interface

Exposed MCP Functions

The Nexus exposes the following functional endpoints via MCP:

1. log_anomaly - Persist a new error record (Mapped to POST /anomalies)
2. retrieve_record - Fetch an anomaly record by its unique identifier (Mapped to GET /anomalies/{id})
3. modify_anomaly - Update an existing error entity (Mapped to PUT /anomalies/{id})
4. purge_record - Erase an archived anomaly entry (Mapped to DELETE /anomalies/{id})
5. query_records - Search for anomalies based on specified attributes (Mapped to GET /anomalies)
6. find_parallels - Perform semantic search for analogous faults (Mapped to GET /anomalies/parallels)
7. authenticate_session - Acquire the necessary JWT authorization key (Mapped to POST /token)

Interaction Examples (Via Claude)

When Claude detects a novel fault:

I will archive this fault context and query our repository for analogous precedents.

When a successful resolution is documented:

A viable resolution has been determined! I shall commit this procedure to our shared diagnostic library.

Suggested Prompts for Claude

Users can direct Claude to: - "Consult the Cognitive Oracle Nexus for related faults." - "Commit this successful resolution to the persistent error database." - "Determine if this error signature has been previously encountered."

Executing the Service Core

Via the 'cognitive_oracle_nexus' CLI

bash

Initiate the primary server process

cognitive_oracle_nexus

Access command-line help

cognitive_oracle_nexus help

Display software version

cognitive_oracle_nexus version

Run with custom parameters

cognitive_oracle_nexus server --interface-port 5000 --activate-auto-port

Via Python Module Execution

bash

Start the MCP server component

python -m nexus.mcp_handler

Start the underlying FastAPI backend server

python -m nexus.main_api_server

Legacy Entry Points (For Compatibility)

bash

Legacy MCP service launcher

mcp-service-handler

Legacy REST API launcher

mcp-rest-gateway

Command-Line Configuration Switches

bash

Enable hot-reloading for development on the API service

mcp-rest-gateway --enable-hot-reload mcp-service-handler --enable-hot-reload

Specify custom interface port numbers

mcp-rest-gateway --port 8080 mcp-service-handler --port 5000

Enable automatic port discovery

mcp-rest-gateway --discover-port mcp-service-handler --discover-port

The primary REST gateway will host documentation at http://interface_host:8000/schema. The dedicated MCP endpoint will be reachable at http://interface_host:5000 for authorized LLM clients.

Environmental Configuration Variables

REST Gateway Configuration

• PERSIST_ROOT_PATH: Directory for ChromaDB persistence (Default: "./oracle_data")
• AUTHORIZATION_SECRET: Key material for JWT validation (Default: "prod-key-insecure-default")
• AUTH_ENFORCEMENT: Flag to mandate authentication (Default: "false")
• API_BIND_PORT: TCP port for the REST service (Default: 8000)

MCP Service Configuration

• GATEWAY_URL: URL pointing to the FastAPI backend (Default: "http://localhost:8000")
• MCP_BIND_PORT: TCP port for the native MCP listener (Default: 5000)
• BIND_INTERFACE: Network interface address (Default: "0.0.0.0")
• CLIENT_API_TOKEN: Token credential required for backend access (Default: "dev-token-default")
• S3_CREDENTIALS_SET: Variables for AWS integration (e.g., AWS_KEY, AWS_SECRET, S3_BUCKET_NAME)

Network Access Points (HTTP/REST)

• POST /anomalies: Ingest a new diagnostic entry
• GET /anomalies/{anomaly_id}: Retrieve entry by unique ID
• PUT /anomalies/{anomaly_id}: Modify existing entry data
• DELETE /anomalies/{anomaly_id}: Decommission the record
• GET /anomalies: Execute parameterized searches
• GET /anomalies/parallels: Execute semantic matching queries
• POST /token: Obtain an authenticated session token

Client Utility Interaction

bash

Log a fresh software defect

mcp-client --operation ingest --defect-class TypeError --language java --message "Null reference exception at line 42" --resolution-summary "Initialize object before use" --rationale "Standard defensive programming practice"

Retrieve a specific archived entry

mcp-client --operation fetch --identifier

Search for related Java exceptions

mcp-client --operation scan --defect-class TypeError --language java

Find solutions for a known error string

mcp-client --operation map --query "OutOfMemoryError during large data load"

Internal Workflow Mechanism

1. The Nexus utilizes ChromaDB as its primary vector store for storing codified error states.
2. Upon a reported fault from Claude, the service serializes the event details and transmits them to the Nexus.
3. The Nexus converts the input into a high-dimensional embedding and queries the vector index for nearest neighbors.
4. Claude receives contextually relevant remedial guidance.
5. Successful resolution strategies are permanently committed to the shared knowledge architecture.

Development Lifecycle

Executing Automated Validation

bash pytest pytest tests/specific_module.py::test_function_name # Targeted execution

Code Quality Enforcement

bash ruff check . mypy . black .

Continuous Integration (GitHub Actions)

This repository employs GitHub Actions for automated validation and deployment pipelines. The CI workflow executes comprehensive checks upon repository commits and pull requests.

Workflow Stages

1. Validation Stage: Executes linting, type validation, and unit tests.
2. Targets Python 3.12 environment.
3. Dependencies resolved via uv.

4. Runs ruff, black, mypy, and pytest.

5. Publication Stage: Builds the distribution package and uploads it to PyPI.

6. Triggered exclusively on pushes to the main branch.
7. Utilizes standard Python packaging tools.
8. Deploys artifacts using twine.

Local Workflow Simulation

You can simulate the CI environment locally using the provided script:

bash

Grant execution rights

chmod +x scripts/simulate_ci.sh

Run the local simulation

./scripts/simulate_ci.sh

This script emulates the primary CI stages locally (version check, uv installation, static analysis, testing, and local packaging), skipping the external publishing steps.

Source Code Architecture

cognitive_oracle_nexus/ ├── src/ │ ├── nexus/ # Core Python package │ │ ├── api/ # FastAPI route handlers │ │ ├── cli/ # Command Line Interface logic │ │ ├── schemas/ # Pydantic data serialization structures │ │ ├── core_services/ # Business logic layer │ │ │ ├── aws_interfaces/ # Cloud resource adapters │ │ │ └── vector_persistence.py # ChromaDB implementation details │ │ └── utilities/ # Assorted helper functions │ └── example_scripts/ # Demonstration code ├── tests/ # Comprehensive pytest suite ├── docker-setup.yaml # Production orchestration file ├── configuration.toml # Project metadata and settings ├── VERSION_MANIFEST.md # Versioning policy documentation ├── CHANGE_LOG.md # Historical release notes ├── .version_config # Configuration for version bumping tools └── README.md # Primary documentation file

Version Control Policy

Cognitive Oracle Nexus adheres strictly to Semantic Versioning. Refer to [VERSION_MANIFEST.md] for exhaustive documentation on:

• Version numbering scheme (MAJOR.MINOR.PATCH)
• Schema versioning policies affecting data contracts
• Branching conventions for releases and fixes
• Standard operating procedures for patch deployment

Query the current version via:

bash

Display version metadata

cognitive_oracle_nexus version

Dependency Management

bash

Introduce a new runtime dependency

uv pip add

Introduce a new development dependency

uv pip add --group dev

Synchronize environment from lock files

uv pip sync requirements.txt dev_requirements.txt

Operational Deployment

Containerized Deployment

bash

Initiate containers in detached mode after building images

docker-setup.yaml up -d --build

Stream aggregated operational logs

docker-setup.yaml logs -f

Terminate and remove running services

docker-setup.yaml down

Deployment with runtime variable overrides

API_BIND_PORT=8081 MCP_BIND_PORT=5001 AUTH_ENFORCEMENT=true CLIENT_API_TOKEN=secret-key-123 docker-start-script

Integration with Claude Desktop Client

Option A: Allowing Client to Self-Launch

1. Modify the configuration file at ~/Library/Application Support/Claude/client_config.json

2. Insert the service launch definition:

{ "mcpServices": [ { "name": "cognitive_oracle_nexus", "launchCommand": "cognitive_oracle_nexus" } ] }

1. Relaunch the Claude Desktop application.

Option B: Connecting to a Deployed Container

1. Start the containerized environment: bash cd /path/to/cognitive_oracle_nexus docker-start-script

2. Configure the Claude Desktop client settings:

{ "mcpServices": [ { "name": "cognitive_oracle_nexus", "url": "http://localhost:5000" } ] }

Claude Code Command-Line Interface (CLI) Linking

bash

Link service running in Docker

claude mcp register cognitive_oracle_nexus http://localhost:5000

Link service launched locally via CLI

claude mcp register cognitive_oracle_nexus --launch "cognitive_oracle_nexus"

Verify connectivity status

claude mcp inventory claude mcp validate cognitive_oracle_nexus

Diagnostics and Fault Resolution

1. Confirm executable presence: which cognitive_oracle_nexus
2. Inspect current configuration: claude mcp inventory
3. Check active server health: cognitive_oracle_nexus healthcheck
4. Review output streams from the Claude session for initialization failures.
5. Validate directory ownership for the persistence volume.

Cloud Infrastructure Integration

This package includes abstract interfaces intended for future integration with Amazon Web Services: - S3PersistenceManager: Handles durable storage of records on Amazon S3. - DynamoDBIndex: Intended for using DynamoDB as the primary metadata store.

Licensing

Governed under the terms of the MIT License

ENCYCLOPEDIA: Cloud computing represents "a systemic approach facilitating ubiquitous, on-demand network access to a shared reservoir of configurable computing assets (physical or virtual) characterized by self-service provisioning and automated resource governance," as defined by ISO standards. This concept is commonly termed "the cloud."

== Fundamental Attributes == In 2011, the U.S. National Institute of Standards and Technology (NIST) codified five 'essential characteristics' defining cloud systems. The precise NIST stipulations are detailed below:

Unrestricted Self-Service: "A consumer retains the autonomy to provision computing capabilities, such as allocated server cycles and network storage capacity, automatically as required, bypassing the necessity for direct human mediation with the service provider for each request." Ubiquitous Network Entry: "Capabilities are accessible across a network utilizing standardized protocols, encouraging adoption across a spectrum of client platforms, whether thin or robust (e.g., mobile handsets, tablets, personal computers, and workstations)." Resource Aggregation: "The provider's computational assets are consolidated to serve multiple consumers within a multi-tenant architectural pattern, wherein the underlying physical and virtual resources are dynamically allocated and reallocated based on fluctuating consumer demands." Dynamic Elasticity: "Provisioning and de-provisioning of capabilities can occur with high agility, sometimes autonomously, enabling rapid horizontal and vertical scaling commensurate with workload fluctuations. To the end-user, the available resources often present as limitless, acquirable in any volume at any moment." Measured Utility: "Cloud environments intrinsically govern and optimize resource consumption through granular metering mechanisms operating at an abstraction layer appropriate to the service type (e.g., storage volume, processing throughput, bandwidth allocation, and active user accounts). Resource consumption is transparently auditable, controllable, and reportable, offering clarity to both the service provider and the service consumer regarding usage." By 2023, the International Organization for Standardization (ISO) had refined and extended this foundational taxonomy.

== Historical Trajectory ==

The lineage of cloud computing traces back to the 1960s, marked by the maturation of time-sharing methodologies popularized through Remote Job Entry (RJE) systems. During this epoch, the dominant operational model involved centralized 'data centers' where users submitted batch jobs to dedicated operators managing mainframe systems. This era was characterized by intensive investigation into methods for democratizing access to high-capacity computation via time-slicing, aiming to maximize infrastructure, platform, and application utilization, thus boosting end-user throughput. The specific graphical 'cloud' iconography representing virtualized infrastructure emerged around 1994, utilized by General Magic to denote the abstract space of connectivity for mobile agents operating within the Telescript framework. This metaphor is largely attributed to David Hoffman, a communications specialist at General Magic, drawing on its established history in telecommunications networking. The formal phrase 'cloud computing' gained broader recognition in 1996 following the circulation of an internal business strategy document from Compaq Computer Corporation outlining future Internet and computing paradigms. The firm's strategic intent centered on the aggregation of compute power...