OuroborosDB

⚠️ This Project is still in development and not ready for production use. It has security vulnerabilities that will be addressed until it reaches a stable release. ⚠️

Name and Logo

The name "OuroborosDB" is derived from the ancient symbol "Ouroboros," a representation of cyclical events, continuity, and endless return. Historically, it's been a potent symbol across various cultures, signifying the eternal cycle of life, death, and rebirth. In the context of this database, the Ouroboros symbolizes the perpetual preservation and renewal of data. While the traditional Ouroboros depicts a serpent consuming its tail, our version deviates, hinting at both reverence for historical cycles and the importance of continuous adaptation in the face of change.

Development Notes

Current Focus

• Implementing the core database ASAP to validate architectural decisions and ensure the design can meet the requirements.

Future Focus

• Heavy refactoring and optimization
• Security hardening and complete audit of the codebase
• Deterministic testing and fuzzing
• Comprehensive documentation and examples
• Release preparations

Environmental Constraints

Server Hardware Constraints

• Must run with 4GB of RAM and 2 CPU cores
• WAL files must not be larger than 10GB
• For NVMe SSDs optimize for:
  • prioritize index storage
• For HDDs optimize for:
  • prioritize Block storage
  • low write amplification
  • low read amplification
  • disable memory mapping
  • Badger Ideas:
    • put opt.Dir to a faster NVMe or SSD and use the HDD for opt.ValueDir
    • optimize ValueLogFileSize for Block storage

Mobile Hardware Constraints

• RAM
  • Dynamic available RAM via os_proc_available_memory iOS and ActivityManager.getMemoryClass() Android
  • Full Mode must run with 128MB of RAM and 1 CPU core
  • For background mode, RAM might be as low as 24MB
• WAL files must not be larger than 100MB
• ValueLog must not be larger than 50MB
• Optimize for startup time
• Silent Push Notification Constraints (Background Sync)
  • Sync time must be minimal (achievable with BadgerDB)
  • Available RAM 24MB
  • max 30 seconds to sync on iOS
  • max 10 seconds to sync on Android or 10 Minutes with WorkManager
• Battery usage must be minimal
  • No or very little background compactions
  • Consider CPU usage
• Write Amplification is not a problem since all mobile devices use NAND

Legend

Annotation for generated tests:

If a test file is generated by AI, it must include _A before _test.go in the filename, e.g., example_A_test.go. This indicates that the tests were generated by AI.
Humans should not add tests in files with the _A suffix, and should instead create new test files without the _A suffix to indicate that these tests were written by humans.

Annotation legend for function comments:

To indicate the correctness and safety of the logic of functions, the following annotations are used in comments directly after the function definitions, at the same line as func (See examples below):

• // A - Function and was written by AI and was not reviewed by a human.
• // AP - Function was written by AI and was reviewed but the human has found a potential issue which the human marked with a // TODO comment.
• // AC - Function was written by AI and was reviewed and approved by a human that has medium confidence in the correctness and safety of the logic.
• // H - Function was written by a human
• // HP - Function was written by a human but the human has found a potential issue which the human marked with a // TODO comment.
• // HC - A human comprehended the logic of th function in all its dimensions and is confident about its correctness and safety.

If the function has a higher risk profile (e.g., involves complex algorithms, security-sensitive operations, or critical data handling), a P prefix is added for Priority:

All P function must be brought to PHC status before a production release.

We add the indicators directly after the function declaration, although it is normally not common practice in Go, because it makes it easier to see the status of the function for most editors as they show use sticky function declaration.

It is negotiable that AI generated functions must be generated with an // A or // AP annotation after the function declaration func exampleFunction() { // A.

Examples:

// This function does X, Y, and Z.
func exampleFunction() { // A
    // Function is low risk and was written by AI and not reviewed by a human.
}

// This function does X, Y, and Z.
func exampleFunction() { // HC
    // Function is low risk and was comprehended by a human who is confident about its correctness and safety.
}

// This function performs critical operations X, Y, and Z has some funky stuff going on.
func criticalFunction() { // PAP
    // Function is high risk and was comprehended by a human who is confident about its correctness and safety.
}

// This function performs critical operations X, Y, and Z.
func criticalFunction() { // PHC
    // Function is high risk and was comprehended by a human who is confident about its correctness and safety.
}

// If a function has multiline parameters, the annotation goes at the same line as func
func manyParametersFunction( // AC
    param1 string, 
    param2 int, 
    param3 []byte
) error { 
    // function has many parameters, was written by AI and reviewed and approved by a human.
    return nil
}

Logging policy

All logging in this repository should use the pkg/clusterlog package. This ensures logs are recorded in the cluster-wide log, emitted to the configured slog.Logger, and delivered to subscribers via the Carrier transport where applicable.

Exceptions: an exception is allowed only when using pkg/clusterlog would create or risk a subscription loop (circular subscriptions) that could cause self-delivery or unbounded propagation. In such cases, document the justification with a clear // LOGGER referencing the potential subscription loop.

License

ouroboros-db © 2026 Mia Heidenstedt and contributors
SPDX-License-Identifier: AGPL-3.0