| Name | tomldiary JSON |
| Version |
0.0.1
JSON |
| download |
| home_page | None |
| Summary | A lightweight TOML-based memory system for AI agents |
| upload_time | 2025-07-20 20:44:20 |
| maintainer | None |
| docs_url | None |
| author | Jan Siml |
| requires_python | >=3.11 |
| license | None |
| keywords |
memory
ai
agents
toml
preferences
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TOMLDiary
**Memory, Simplified: TOML-Driven, Agent-Approved.**
TOMLDiary is a dead-simple, customizable memory system for agentic applications. It stores data in human-readable TOML files so your agents can keep a tidy diary of only the useful stuff.
## Key Benefits
- **Human-readable TOML storage** – easy to inspect, debug and manage.
- **Fully customizable** – define your own memory schema with simple Pydantic models.
- **Minimal overhead** – lightweight design, backend agnostic and easy to integrate.
- **Atomic, safe writes** – ensures data integrity with proper file locking.
## Installation
Requires Python 3.11+
```bash
uv add tomldiary pydantic-ai
```
## Quick Start
```python
from pydantic import BaseModel
from typing import Dict
from tomldiary import TOMLDiary, PreferenceItem
from tomldiary.backends import LocalBackend
# Be as specific as possible in your preference schema, it passed to the system prompt of the agent extracting the data!
class MyPrefTable(BaseModel):
"""
likes : What the user enjoys
dislikes : Things user avoids
allergies: Substances causing reactions
routines : User’s typical habits
biography: User’s personal details
"""
likes: Dict[str, PreferenceItem] = {}
dislikes: Dict[str, PreferenceItem] = {}
allergies: Dict[str, PreferenceItem] = {}
routines: Dict[str, PreferenceItem] = {}
biography: Dict[str, PreferenceItem] = {}
diary = TOMLDiary(
backend=LocalBackend(path="./memories"),
pref_table_cls=MyPrefTable,
max_prefs_per_category=100,
max_conversations=50,
)
await diary.ensure_session(user_id, session_id)
await diary.update_memory(
user_id,
session_id,
user_message="I'm allergic to walnuts.",
agent_response="I'll remember you're allergic to walnuts.",
)
```
## TOML Memory Example
```toml
[_meta]
version = "0.2"
schema_name = "MyPrefTable"
[allergies.walnuts]
text = "allergic to walnuts"
contexts = ["diet", "health"]
_count = 1
_created = "2024-01-01T00:00:00Z"
_updated = "2024-01-01T00:00:00Z"
```
### Conversations File (`alice_conversations.toml`)
```toml
[_meta]
version = "0.2"
schema_name = "MyPrefTable"
[chat_123]
_created = "2024-01-01T00:00:00Z"
_turns = 5
summary = "Discussed food preferences and dietary restrictions"
keywords = ["food", "allergy", "italian"]
```
## Advanced Usage
### Custom Preference Categories
Create your own preference schema:
```python
class DetailedPrefTable(BaseModel):
"""
dietary : Food preferences and restrictions
medical : Health conditions and medications
interests : Hobbies and topics of interest
goals : Personal objectives and aspirations
family : Family members and relationships
work : Professional information
"""
dietary: Dict[str, PreferenceItem] = {}
medical: Dict[str, PreferenceItem] = {}
interests: Dict[str, PreferenceItem] = {}
goals: Dict[str, PreferenceItem] = {}
family: Dict[str, PreferenceItem] = {}
work: Dict[str, PreferenceItem] = {}
```
### Backend Options
The library supports different storage backends:
```python
# Local filesystem (default)
from tomldiary.backends import LocalBackend
backend = LocalBackend(Path("./memories"))
# S3 backend (implement S3Backend)
# backend = S3Backend(bucket="my-memories")
# Redis backend (implement RedisBackend)
# backend = RedisBackend(host="localhost")
```
### Memory Writer Configuration
```python
# Configure the background writer
writer = MemoryWriter(
diary=diary,
workers=3, # Number of background workers
qsize=100, # Queue size
retry_limit=3, # Max retries on failure
retry_delay=1.0 # Delay between retries
)
```
## API Reference
### TOMLDiary
Main class for memory operations:
- `preferences(user_id)`: Get user preferences as TOML string
- `last_conversations(user_id, n)`: Get last N conversation summaries
- `ensure_session(user_id, session_id)`: Create session if needed
- `update_memory(user_id, session_id, user_msg, assistant_msg)`: Process and store memory
### MemoryWriter
Background queue for non-blocking writes:
- `submit(user_id, session_id, user_message, assistant_response)`: Queue memory update
- `close()`: Graceful shutdown
- `failed_count()`: Number of failed operations
### Models
- `PreferenceItem`: Single preference with text, contexts, and metadata
- `ConversationItem`: Conversation with summary, keywords, and turn count
- `MemoryDeps`: Container for preferences and conversations
## Examples
See the `examples/` directory for:
- `example_simple_demo.py`: Basic usage without LLM
- `example_tomldiary.py`: Full LLM integration
- `example_multi_user.py`: Concurrent multi-user scenario
## Development
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
ruff format .
# Lint code
ruff check .
```
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "tomldiary",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "memory, ai, agents, toml, preferences",
"author": "Jan Siml",
"author_email": "Jan Siml <49557684+svilupp@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/21/b1/3dd7e3c3151cf6ee07300e639624eb829a0bdfa6c6da4261b4d2b0a8c12c/tomldiary-0.0.1.tar.gz",
"platform": null,
"description": "# TOMLDiary\n\n**Memory, Simplified: TOML-Driven, Agent-Approved.**\n\nTOMLDiary is a dead-simple, customizable memory system for agentic applications. It stores data in human-readable TOML files so your agents can keep a tidy diary of only the useful stuff.\n\n## Key Benefits\n\n- **Human-readable TOML storage** \u2013 easy to inspect, debug and manage.\n- **Fully customizable** \u2013 define your own memory schema with simple Pydantic models.\n- **Minimal overhead** \u2013 lightweight design, backend agnostic and easy to integrate.\n- **Atomic, safe writes** \u2013 ensures data integrity with proper file locking.\n\n## Installation\n\nRequires Python 3.11+\n\n```bash\nuv add tomldiary pydantic-ai\n```\n\n## Quick Start\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Dict\nfrom tomldiary import TOMLDiary, PreferenceItem\nfrom tomldiary.backends import LocalBackend\n\n# Be as specific as possible in your preference schema, it passed to the system prompt of the agent extracting the data!\nclass MyPrefTable(BaseModel):\n \"\"\"\n likes : What the user enjoys\n dislikes : Things user avoids\n allergies: Substances causing reactions\n routines : User\u2019s typical habits\n biography: User\u2019s personal details\n \"\"\"\n\n likes: Dict[str, PreferenceItem] = {}\n dislikes: Dict[str, PreferenceItem] = {}\n allergies: Dict[str, PreferenceItem] = {}\n routines: Dict[str, PreferenceItem] = {}\n biography: Dict[str, PreferenceItem] = {}\n\n\ndiary = TOMLDiary(\n backend=LocalBackend(path=\"./memories\"),\n pref_table_cls=MyPrefTable,\n max_prefs_per_category=100,\n max_conversations=50,\n)\n\nawait diary.ensure_session(user_id, session_id)\nawait diary.update_memory(\n user_id,\n session_id,\n user_message=\"I'm allergic to walnuts.\",\n agent_response=\"I'll remember you're allergic to walnuts.\",\n)\n```\n\n## TOML Memory Example\n\n```toml\n[_meta]\nversion = \"0.2\"\nschema_name = \"MyPrefTable\"\n\n[allergies.walnuts]\ntext = \"allergic to walnuts\"\ncontexts = [\"diet\", \"health\"]\n_count = 1\n_created = \"2024-01-01T00:00:00Z\"\n_updated = \"2024-01-01T00:00:00Z\"\n```\n\n### Conversations File (`alice_conversations.toml`)\n```toml\n[_meta]\nversion = \"0.2\"\nschema_name = \"MyPrefTable\"\n\n[chat_123]\n_created = \"2024-01-01T00:00:00Z\"\n_turns = 5\nsummary = \"Discussed food preferences and dietary restrictions\"\nkeywords = [\"food\", \"allergy\", \"italian\"]\n```\n\n## Advanced Usage\n\n### Custom Preference Categories\n\nCreate your own preference schema:\n\n```python\nclass DetailedPrefTable(BaseModel):\n \"\"\"\n dietary : Food preferences and restrictions\n medical : Health conditions and medications\n interests : Hobbies and topics of interest\n goals : Personal objectives and aspirations\n family : Family members and relationships\n work : Professional information\n \"\"\"\n dietary: Dict[str, PreferenceItem] = {}\n medical: Dict[str, PreferenceItem] = {}\n interests: Dict[str, PreferenceItem] = {}\n goals: Dict[str, PreferenceItem] = {}\n family: Dict[str, PreferenceItem] = {}\n work: Dict[str, PreferenceItem] = {}\n```\n\n### Backend Options\n\nThe library supports different storage backends:\n\n```python\n# Local filesystem (default)\nfrom tomldiary.backends import LocalBackend\nbackend = LocalBackend(Path(\"./memories\"))\n\n# S3 backend (implement S3Backend)\n# backend = S3Backend(bucket=\"my-memories\")\n\n# Redis backend (implement RedisBackend) \n# backend = RedisBackend(host=\"localhost\")\n```\n\n### Memory Writer Configuration\n\n```python\n# Configure the background writer\nwriter = MemoryWriter(\n diary=diary,\n workers=3, # Number of background workers\n qsize=100, # Queue size\n retry_limit=3, # Max retries on failure\n retry_delay=1.0 # Delay between retries\n)\n```\n\n## API Reference\n\n### TOMLDiary\n\nMain class for memory operations:\n\n- `preferences(user_id)`: Get user preferences as TOML string\n- `last_conversations(user_id, n)`: Get last N conversation summaries\n- `ensure_session(user_id, session_id)`: Create session if needed\n- `update_memory(user_id, session_id, user_msg, assistant_msg)`: Process and store memory\n\n### MemoryWriter\n\nBackground queue for non-blocking writes:\n\n- `submit(user_id, session_id, user_message, assistant_response)`: Queue memory update\n- `close()`: Graceful shutdown\n- `failed_count()`: Number of failed operations\n\n### Models\n\n- `PreferenceItem`: Single preference with text, contexts, and metadata\n- `ConversationItem`: Conversation with summary, keywords, and turn count\n- `MemoryDeps`: Container for preferences and conversations\n\n## Examples\n\nSee the `examples/` directory for:\n- `example_simple_demo.py`: Basic usage without LLM\n- `example_tomldiary.py`: Full LLM integration\n- `example_multi_user.py`: Concurrent multi-user scenario\n\n## Development\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nruff format .\n\n# Lint code\nruff check .\n```\n\n## License\n\nMIT License - see LICENSE file for details.",
"bugtrack_url": null,
"license": null,
"summary": "A lightweight TOML-based memory system for AI agents",
"version": "0.0.1",
"project_urls": {
"Documentation": "https://github.com/svilupp/tomldiary/tree/main/docs",
"Homepage": "https://github.com/svilupp/tomldiary",
"Issues": "https://github.com/svilupp/tomldiary/issues",
"Repository": "https://github.com/svilupp/tomldiary"
},
"split_keywords": [
"memory",
" ai",
" agents",
" toml",
" preferences"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3b2957572f810daeff9227fc0b93f368dbf72e495552831b5824faff0922d679",
"md5": "d3a2e24373fc71046ee6ef955876bb62",
"sha256": "c51b39fd3deb95de0e53748292c893fb1d1ba7faf18c1058c2d57a8989a348e8"
},
"downloads": -1,
"filename": "tomldiary-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3a2e24373fc71046ee6ef955876bb62",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 15503,
"upload_time": "2025-07-20T20:44:18",
"upload_time_iso_8601": "2025-07-20T20:44:18.720059Z",
"url": "https://files.pythonhosted.org/packages/3b/29/57572f810daeff9227fc0b93f368dbf72e495552831b5824faff0922d679/tomldiary-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "21b13dd7e3c3151cf6ee07300e639624eb829a0bdfa6c6da4261b4d2b0a8c12c",
"md5": "9dd4c902b62f73b6e2f3671cd44649ba",
"sha256": "e0c6e2a2378509b397b970bb022878c56a40520e1ebbdcbd54ddeff6afe69b04"
},
"downloads": -1,
"filename": "tomldiary-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "9dd4c902b62f73b6e2f3671cd44649ba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 12206,
"upload_time": "2025-07-20T20:44:20",
"upload_time_iso_8601": "2025-07-20T20:44:20.329984Z",
"url": "https://files.pythonhosted.org/packages/21/b1/3dd7e3c3151cf6ee07300e639624eb829a0bdfa6c6da4261b4d2b0a8c12c/tomldiary-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-20 20:44:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "svilupp",
"github_project": "tomldiary",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tomldiary"
}
