agentmemo 0.1.0__tar.gz

agentmemo-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Something doesn't work as expected
+labels: bug
+---
+
+## Environment
+
+- OS: <!-- e.g. macOS 14, Ubuntu 22.04, Windows 11 -->
+- Python version: <!-- e.g. 3.11.9 -->
+- agentmemo version: <!-- e.g. 0.1.0 — run `agentmemo --version` or `pip show agentmemo` -->
+- Storage backend: <!-- yaml / sqlite / postgres -->
+- LLM provider: <!-- openai / anthropic / yandex / gigachat / qwen / openai-compat -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behaviour
+
+<!-- What should happen -->
+
+## Actual behaviour
+
+<!-- What actually happens — include the full traceback if there is one -->
+
+```
+paste error output here
+```
+
+## Minimal reproducing example
+
+```python
+# Paste the smallest snippet that triggers the bug
+```
+
+## Additional context
+
+<!-- Anything else that might be relevant: custom storage path, concurrent access, specific LLM model, etc. -->

agentmemo-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: Feature request
+about: Propose a new feature or improvement
+labels: enhancement
+---
+
+## Problem
+
+<!-- What are you trying to do that agentmemo doesn't support yet?
+     Be specific: "I want to store facts in Redis" is better than "more backends". -->
+
+## Proposed solution
+
+<!-- How would you like it to work? Include API sketch if relevant. -->
+
+```python
+# Example of what the API could look like
+```
+
+## Alternatives considered
+
+<!-- What workarounds have you tried? Why don't they work for your case? -->
+
+## Would you be willing to implement this?
+
+- [ ] Yes, I can open a PR
+- [ ] I can help test/review
+- [ ] No, just reporting the need
+
+## Additional context
+
+<!-- Links, related issues, prior art in other libraries, etc. -->

agentmemo-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,45 @@
+## Summary
+
+<!-- What does this PR do? 2-3 bullet points. -->
+
+- 
+- 
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactoring (no functional change)
+- [ ] Documentation
+- [ ] CI / DevOps
+
+## Principal Python Developer review checklist
+
+> Reviewer applies `skills/principal_python_developer.md` before approving.
+
+- [ ] All public classes and functions have docstrings
+- [ ] `from __future__ import annotations` present in every new module
+- [ ] All type annotations correct and `mypy --strict` passes
+- [ ] No bare `except:` — specific exceptions only
+- [ ] No mutable default arguments (use `field(default_factory=...)`)
+- [ ] `StorageBackend` protocol fully satisfied (if storage changes)
+- [ ] No hardcoded secrets or absolute paths
+- [ ] `ruff check` and `ruff format --check` pass clean
+
+## Test checklist
+
+- [ ] New behaviour covered by unit tests
+- [ ] LLM calls mocked (no real API calls in tests)
+- [ ] Storage tests include round-trip + multi-agent isolation
+- [ ] `pytest --cov-fail-under=80` passes
+- [ ] Both YAML and SQLite backends tested (if storage-related)
+
+## Documentation
+
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
+- [ ] Docstrings updated for changed public API
+- [ ] `ARCHITECTURE.md` updated if new layer or extension point added
+
+## Screenshots / output (if applicable)
+
+<!-- Paste CLI output or relevant logs -->

agentmemo-0.1.0/.github/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in agentmemo, please report it responsibly:
+
+1. **Do not** open a public issue.
+2. Email the maintainers or open a private security advisory via
+   [GitHub Security Advisories](https://github.com/alsoleg89/agentmemo/security/advisories/new).
+3. Include a description of the vulnerability, steps to reproduce, and potential impact.
+
+We will acknowledge receipt within 48 hours and aim to release a fix within 7 days
+for critical issues.
+
+## Scope
+
+- agentmemo library code (`src/agentmemo/`)
+- CLI interface
+- Storage backends (YAML, SQLite, PostgreSQL)
+- LLM provider integrations
+
+## Out of Scope
+
+- Vulnerabilities in third-party dependencies (report upstream)
+- Issues requiring physical access to the machine
+- Social engineering attacks

agentmemo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check src/ tests/
+
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+
+      - name: Mypy
+        run: mypy src/agentmemo/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,openai]"
+
+      - name: Run tests
+        run: pytest --cov=agentmemo --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

agentmemo-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install hatch
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agentmemo-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+*.whl
+.venv/
+venv/
+env/
+.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+coverage.xml
+.coverage
+.coverage.*
+*.log
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.agentmemo/

agentmemo-0.1.0/.mlc-config.json

@@ -0,0 +1,29 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^https://shields\\.io"
+    },
+    {
+      "pattern": "^https://img\\.shields\\.io"
+    },
+    {
+      "pattern": "^https://github\\.com/.*/actions/workflows"
+    },
+    {
+      "pattern": "^https://pypi\\.org/project/agentmemo"
+    },
+    {
+      "pattern": "^http://localhost"
+    },
+    {
+      "pattern": "^https://github\\.com/alsoleg89/agentmemo/compare/"
+    },
+    {
+      "pattern": "^https://github\\.com/alsoleg89/agentmemo/releases/tag/"
+    }
+  ],
+  "timeout": "10s",
+  "retryOn429": true,
+  "retryCount": 3,
+  "aliveStatusCodes": [200, 206]
+}

agentmemo-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - types-PyYAML>=6.0
+          - httpx>=0.27
+        args: [--strict]

agentmemo-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,152 @@
+# agentmemo — Architecture
+
+## Design goals
+
+| Goal | How |
+|---|---|
+| **Zero vendor lock-in** | Pluggable `StorageBackend` protocol |
+| **Zero mandatory cloud deps** | Only `click`, `pyyaml`, `httpx` required |
+| **Human-readable storage** | YAML files by default |
+| **Signal over noise** | LLM distillation + Ebbinghaus decay |
+| **Framework-agnostic** | Plain Python objects, no base classes to inherit |
+
+---
+
+## Layer diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  CLI (agentmemo.cli)          Integrations (*.integrations) │
+├─────────────────────────────────────────────────────────────┤
+│                  KnowledgeBase (agentmemo.knowledge)         │  ← public API
+├──────────────┬──────────────────┬───────────────────────────┤
+│  Extractor   │  TFIDFRetriever  │  apply_decay / forgetting  │
+│  (LLM calls) │  (TF-IDF search) │  (Ebbinghaus curve)        │
+├──────────────┴──────────────────┴───────────────────────────┤
+│              StorageBackend (protocol)                        │
+│  YAMLStorage          SQLiteStorage         (future: PG …)  │
+├─────────────────────────────────────────────────────────────┤
+│              Core types: Fact, MemoryType, ConversationTurn   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Dependency rules (no circular imports)
+
+```
+types  ←  storage  ←  forgetting
+                  ←  retriever
+                  ←  extractor
+                  ←  knowledge  ←  cli
+                                ←  integrations
+```
+
+`knowledge.py` is the top of the internal dependency graph.  
+Nothing in `storage/`, `forgetting.py`, or `retriever.py` may import from `knowledge.py`.
+
+---
+
+## Core types (`agentmemo.types`)
+
+### `Fact`
+The atomic unit of knowledge.
+
+| Field | Type | Description |
+|---|---|---|
+| `content` | `str` | Human-readable knowledge string |
+| `type` | `MemoryType` | `semantic` / `procedural` / `episodic` |
+| `importance` | `float` | 0.0–1.0; controls decay speed |
+| `retention_score` | `float` | Current Ebbinghaus score (updated on recall) |
+| `access_count` | `int` | Times retrieved — increases stability |
+| `tags` | `list[str]` | Optional labels |
+| `id` | `str` | 8-char UUID hex |
+| `created_at` | `datetime` | UTC |
+| `last_accessed` | `datetime` | UTC |
+
+### `MemoryType`
+`SEMANTIC` — facts about the world/user  
+`PROCEDURAL` — how the user wants things done  
+`EPISODIC` — specific past events  
+
+---
+
+## Storage layer
+
+### `StorageBackend` protocol
+
+```python
+def save(self, agent_id: str, facts: list[Fact]) -> None: ...
+def load(self, agent_id: str) -> list[Fact]: ...
+def delete(self, agent_id: str, fact_id: str) -> None: ...
+def list_agents(self) -> list[str]: ...
+```
+
+`save` is a **full replace** — the caller always loads, mutates, then saves.
+
+Backends are responsible for:
+- Namespacing by `agent_id`
+- Serialising all `Fact` fields including datetime with UTC timezone
+
+### YAMLStorage
+File layout: `{base_dir}/{agent_id}/knowledge.yaml`  
+Key: `fact.id` (8-char hex)  
+Human-readable, Git-trackable, editable by hand.
+
+### SQLiteStorage
+Single `.db` file. Schema:
+```sql
+CREATE TABLE facts (
+    id TEXT, agent_id TEXT,
+    content TEXT, type TEXT,
+    importance REAL, retention REAL,
+    access_count INTEGER, tags TEXT,
+    created_at TEXT, last_accessed TEXT,
+    PRIMARY KEY (agent_id, id)
+)
+```
+
+---
+
+## Forgetting curve (`agentmemo.forgetting`)
+
+```
+retention(t) = exp(−t / stability)
+
+stability = 168h × importance × (1 + ln(1 + access_count))
+```
+
+- `t` = hours since `last_accessed`
+- Base stability = 168 h (1 week) for `importance=1.0, access_count=0`
+- Applied via `apply_decay(facts)` **before** every retrieval in `KnowledgeBase.recall()`
+- After retrieval, `access_count` is incremented and `last_accessed` is updated → reinforcement
+
+---
+
+## Retrieval (`agentmemo.retriever`)
+
+`TFIDFRetriever.search(query, facts, top_k)` — zero external dependencies.
+
+Scoring:
+```
+hybrid_score = 0.6 × tfidf + 0.2 × retention_score + 0.2 × importance
+```
+
+TF-IDF is computed fresh per query (no index) — suitable for knowledge bases up to ~10k facts.
+
+---
+
+## Extraction (`agentmemo.extractor`)
+
+`Extractor.extract(turns)` sends the conversation to an LLM and parses the returned JSON array of facts.  
+Supports `openai` and `anthropic` providers via `httpx`.  
+Deduplication: Jaccard word-similarity ≥ 0.8 → keep first occurrence.
+
+---
+
+## Extension points
+
+| What | Where | Interface |
+|---|---|---|
+| New storage backend | `src/agentmemo/storage/` | `StorageBackend` protocol |
+| New LLM provider | `Extractor._call_<provider>` | Returns `list[dict]` from LLM |
+| New integration | `src/agentmemo/integrations/` | Import `KnowledgeBase`, wrap |
+| New retriever | Replace `TFIDFRetriever` | `.search(query, facts, top_k)` |

agentmemo-0.1.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to agentmemo are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning: [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+### Planned
+- MongoDB storage backend
+- Qdrant and Weaviate backends
+- Semantic embeddings (sentence-transformers / OpenAI)
+- MCP server support
+- LangChain / CrewAI integrations
+- Web UI knowledge inspector
+- REST API / sidecar mode
+
+---
+
+## [0.1.0] — 2026-03-28
+
+### Added
+- **Core `KnowledgeBase`** with `add`, `learn`, `recall`, `forget`, `decay`, `stats`
+- **Ebbinghaus forgetting curve** — `forgetting.py`
+  `retention = exp(−t / stability)` where `stability = 336h × importance × (1 + ln(1 + access_count))`
+- **TF-IDF retriever** — zero external dependencies, hybrid score with retention and importance boost
+- **LLM fact extractor** — Jaccard deduplication, markdown fence stripping
+- **6 LLM providers** — OpenAI, Anthropic (Claude), GigaChat (Sber), Yandex GPT, Qwen, generic OpenAI-compatible
+- **Pluggable LLM providers** — `LLMProvider` Protocol with `call_with_retry()` shared retry logic
+- **Provider factory** — `create_provider("openai"|"anthropic"|"gigachat"|"yandex"|"qwen"|"openai-compat")`
+- **Env var API key resolution** — `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GIGACHAT_API_KEY`, `YANDEX_API_KEY`, `QWEN_API_KEY`, `LLM_API_KEY`
+- **YAML storage backend** — human-readable, Git-trackable, editable by hand; thread-safe with per-file lock + atomic write
+- **SQLite storage backend** — zero-server production storage with WAL mode
+- **PostgreSQL storage backend** — provide a DSN, table auto-created; `pip install agentmemo[postgres]`
+- **Configurable storage** — `create_storage("yaml"|"sqlite"|"postgres")` factory; CLI `--storage` / `--dsn` options
+- **`StorageBackend` protocol** — plug-in interface for custom backends
+- **OpenAI integration** — `MemoryEnabledOpenAI` wraps message lists with memory context injection
+- **CLI** — `show`, `add`, `recall`, `stats`, `decay`, `clear`, `export`, `import` commands with `--data-dir`, `--storage`, `--dsn` group options
+- **Core types** — `Fact`, `MemoryType` (StrEnum), `ConversationTurn`
+- **Full test suite** — 235+ tests, 80%+ coverage, both backends parametrized, all LLM calls mocked
+- **32 simulation scenarios** — end-to-end tests for memory, storage, providers, CLI, and integrations
+- **Performance benchmarks** — `test_performance.py` with `@pytest.mark.slow`
+- **pytest markers** — `unit`, `integration`, `slow`, `requires_api_key`
+- **GitHub Actions CI** — lint + type check + test on Python 3.11 & 3.12
+- **GitHub Actions publish** — PyPI Trusted Publishing on `v*` tags
+- **PEP 561** — `py.typed` marker file
+- **pre-commit config** — ruff lint+format + mypy hooks
+- **Security policy** — `.github/SECURITY.md`
+- **Project documentation** — README, CONTRIBUTING, ARCHITECTURE, DEVELOPMENT, skills/
+
+### Changed (since initial development)
+- Extractor refactored to use `LLMProvider` Protocol (removed duplicated retry logic)
+- `KnowledgeBase.learn()` accepts provider name or `LLMProvider` instance + `**provider_kwargs`
+- `MemoryEnabledOpenAI.enrich_messages()` is now a public method
+- `datetime.UTC` alias used everywhere (Python 3.11+)
+- Input validation in `KnowledgeBase.add()` and CLI `add`/`import` commands
+- `BASE_STABILITY_HOURS` set to 336 (2 weeks retention baseline)
+- TF-IDF tokenizer: camelCase splitting + basic plural stemming
+
+[Unreleased]: https://github.com/alsoleg89/agentmemo/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/alsoleg89/agentmemo/releases/tag/v0.1.0

agentmemo-0.1.0/CLAUDE.md

@@ -0,0 +1,40 @@
+# Dev Notes
+
+## Git workflow
+
+**Never push directly to `main`.** No exceptions.
+
+- All changes go to a feature branch
+- To merge into `main`: open a pull request, wait for maintainer approval
+- Force-pushing `main` is forbidden
+- To fix something on `main`: branch → commit → PR → merge
+
+## Commit conventions
+
+**Author**: commits must be attributed to the project maintainer:
+`alsoleg89 <155813332+alsoleg89@users.noreply.github.com>`
+
+Verify before pushing:
+```bash
+git log -1 --format="%an"   # must be: alsoleg89
+```
+
+**Subject line** — keep it short and factual. Avoid:
+- Tool or service names (editor, AI assistant, CI bot names)
+- Internal workflow jargon (audit names, pipeline step names)
+- Auto-generated session or trace URLs
+
+**Body** — optional. If present: one blank line after subject, then context.
+No auto-generated footers or URLs.
+
+**Merge commits** — subject must not expose internal branch naming conventions.
+
+## Sanity check before push
+
+```bash
+# Confirm author
+git log --format="%an" | sort -u
+
+# Confirm no leaked URLs
+git log --format="%B" | grep "https://claude\|session_"
+```

agentmemo-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening a GitHub issue or contacting the maintainers directly via GitHub. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.