{"_id":"@agent-runner/store-sqlite","_rev":"2-968d20d9fc9075c1ff77b83db7d55eab","name":"@agent-runner/store-sqlite","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agent-runner/store-sqlite","version":"0.1.0","keywords":["agent-runner","sqlite","store","ai","agents"],"author":{"name":"Aaron Bidworthy"},"license":"MIT","_id":"@agent-runner/store-sqlite@0.1.0","maintainers":[{"name":"aparry3","email":"aaron.parry.18@gmail.com"}],"homepage":"https://github.com/aparry3/agent-runner#readme","bugs":{"url":"https://github.com/aparry3/agent-runner/issues"},"dist":{"shasum":"72534803d0a5c61ac8417c590ebff02712ace659","tarball":"https://registry.npmjs.org/@agent-runner/store-sqlite/-/store-sqlite-0.1.0.tgz","fileCount":4,"integrity":"sha512-ffxYgXxnZOSr0bxydj0UoypD/njOLf8H+LjPEDJWR2Vf5Fy08seOpof6UEkGcFiupMVorkOYomS9Hx2woFQLlw==","signatures":[{"sig":"MEUCIDDDvXUFjiS/od29ZwndCGOH9DsJhlSVKbSht1NH6X48AiEA3voT1+XaH2k6S6GjIroYRAkhyTW9ZdfyEZOAKvQGkw4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34052},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"15bbcff48ae585a4816b8d26f0625634da2adbea","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"tsup"},"_npmUser":{"name":"aparry3","email":"aaron.parry.18@gmail.com"},"repository":{"url":"git+https://github.com/aparry3/agent-runner.git","type":"git","directory":"packages/store-sqlite"},"_npmVersion":"10.9.4","description":"SQLite store adapter for agent-runner — single-server production storage","directories":{},"_nodeVersion":"22.21.0","dependencies":{"better-sqlite3":"^11.8.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^2.0.0","typescript":"^5.7.0","@agent-runner/core":"workspace:*","@types/better-sqlite3":"^7.6.12"},"peerDependencies":{"@agent-runner/core":">=0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/store-sqlite_0.1.0_1773227442226_0.5654621327487441","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agent-runner/store-sqlite","version":"0.1.1","description":"SQLite store adapter for agent-runner — single-server production storage","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"dependencies":{"better-sqlite3":"^11.8.1"},"devDependencies":{"@types/better-sqlite3":"^7.6.12","tsup":"^8.0.0","typescript":"^5.7.0","vitest":"^2.0.0","@agent-runner/core":"0.1.1"},"peerDependencies":{"@agent-runner/core":">=0.1.1"},"keywords":["agent-runner","sqlite","store","ai","agents"],"publishConfig":{"access":"public"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aparry3/agent-runner.git","directory":"packages/store-sqlite"},"homepage":"https://github.com/aparry3/agent-runner#readme","author":{"name":"Aaron Bidworthy"},"engines":{"node":">=20.0.0"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit"},"_id":"@agent-runner/store-sqlite@0.1.1","bugs":{"url":"https://github.com/aparry3/agent-runner/issues"},"_integrity":"sha512-xNLy7CQal5ZdLigVD0d8gfgWvnUS+K+JpB8EJhkR6EaWPS4/nC/eIths2QulpDMFo46jePdzng5zFMfQ8LHSZA==","_resolved":"/tmp/e6554c04e53f546a98c9141acf7afefc/agent-runner-store-sqlite-0.1.1.tgz","_from":"file:agent-runner-store-sqlite-0.1.1.tgz","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-xNLy7CQal5ZdLigVD0d8gfgWvnUS+K+JpB8EJhkR6EaWPS4/nC/eIths2QulpDMFo46jePdzng5zFMfQ8LHSZA==","shasum":"0fb2c4f7b2e2475980e41c90b878feb33d5c469d","tarball":"https://registry.npmjs.org/@agent-runner/store-sqlite/-/store-sqlite-0.1.1.tgz","fileCount":6,"unpackedSize":42891,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDZTvzuQE+hpeClk18dsM855lcIDxRrx0gTixWx/Pry2AIhAPvfj7o58uXZXznwqJTnyqDP9JnFMB/3P9WEITUhZto1"}]},"_npmUser":{"name":"aparry3","email":"aaron.parry.18@gmail.com"},"directories":{},"maintainers":[{"name":"aparry3","email":"aaron.parry.18@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/store-sqlite_0.1.1_1773230666183_0.37593925979902276"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-11T11:10:42.154Z","modified":"2026-03-11T12:04:26.490Z","0.1.0":"2026-03-11T11:10:42.363Z","0.1.1":"2026-03-11T12:04:26.359Z"},"bugs":{"url":"https://github.com/aparry3/agent-runner/issues"},"author":{"name":"Aaron Bidworthy"},"license":"MIT","homepage":"https://github.com/aparry3/agent-runner#readme","keywords":["agent-runner","sqlite","store","ai","agents"],"repository":{"type":"git","url":"git+https://github.com/aparry3/agent-runner.git","directory":"packages/store-sqlite"},"description":"SQLite store adapter for agent-runner — single-server production storage","maintainers":[{"name":"aparry3","email":"aaron.parry.18@gmail.com"}],"readme":"# @agent-runner/store-sqlite\n\n[![npm version](https://img.shields.io/npm/v/@agent-runner/store-sqlite.svg)](https://www.npmjs.com/package/@agent-runner/store-sqlite)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)\n\nSQLite storage adapter for [agent-runner](https://github.com/aparry3/agent-runner). Zero-config persistent storage for single-server deployments with WAL mode, automatic migrations, and full-text search on logs.\n\nBuilt on [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) for synchronous, high-performance access.\n\n## Install\n\n```bash\nnpm install @agent-runner/store-sqlite @agent-runner/core\n# or\npnpm add @agent-runner/store-sqlite @agent-runner/core\n# or\nyarn add @agent-runner/store-sqlite @agent-runner/core\n```\n\n## Quick Start\n\n```typescript\nimport { createRunner, defineAgent } from \"@agent-runner/core\";\nimport { SqliteStore } from \"@agent-runner/store-sqlite\";\n\nconst runner = createRunner({\n  store: new SqliteStore(\"./data.db\"),\n});\n\nrunner.registerAgent(defineAgent({\n  id: \"greeter\",\n  name: \"Greeter\",\n  systemPrompt: \"You are a friendly greeter.\",\n  model: { provider: \"openai\", name: \"gpt-4o-mini\" },\n}));\n\nconst result = await runner.invoke(\"greeter\", \"Hello!\");\nconsole.log(result.output);\n```\n\nThat's it. The database file is created automatically with all tables and indexes.\n\n## Usage\n\n### File-Based Storage\n\nThe most common setup — a single file that persists everything:\n\n```typescript\nconst store = new SqliteStore(\"./data.db\");\n```\n\nThis creates (or opens) `./data.db` with WAL mode enabled for concurrent read performance.\n\n### In-Memory Storage\n\nFor testing or ephemeral workloads:\n\n```typescript\nconst store = new SqliteStore(\":memory:\");\n```\n\nSame API, same schema — data lives only in memory.\n\n### Full Options\n\n```typescript\nconst store = new SqliteStore({\n  path: \"./data.db\",\n  wal: true,       // WAL mode for better concurrent reads (default: true)\n  verbose: false,  // Log all SQL queries to console (default: false)\n});\n```\n\n## API Reference\n\n### `SqliteStore`\n\nImplements `UnifiedStore` from `@agent-runner/core` — provides `AgentStore`, `SessionStore`, `ContextStore`, and `LogStore` in a single class.\n\n#### Constructor\n\n```typescript\nnew SqliteStore(path: string)\nnew SqliteStore(options: SqliteStoreOptions)\n```\n\n#### `SqliteStoreOptions`\n\n| Option | Type | Default | Description |\n|---|---|---|---|\n| `path` | `string` | — | **Required.** Path to SQLite file, or `\":memory:\"` |\n| `wal` | `boolean` | `true` | Enable WAL journal mode |\n| `verbose` | `boolean` | `false` | Log all SQL queries to console |\n\n#### Store Methods\n\n**AgentStore:**\n\n| Method | Description |\n|---|---|\n| `getAgent(id)` | Get an agent definition by ID |\n| `listAgents()` | List all agents (id, name, description) |\n| `putAgent(agent)` | Create or update an agent (upsert) |\n| `deleteAgent(id)` | Delete an agent |\n\n**SessionStore:**\n\n| Method | Description |\n|---|---|\n| `getMessages(sessionId)` | Get all messages in a session |\n| `append(sessionId, messages)` | Append messages (creates session if needed) |\n| `deleteSession(sessionId)` | Delete a session and its messages |\n| `listSessions(agentId?)` | List sessions, optionally filtered by agent |\n\n**ContextStore:**\n\n| Method | Description |\n|---|---|\n| `getContext(contextId)` | Get all entries for a context bucket |\n| `addContext(contextId, entry)` | Add an entry to a context bucket |\n| `clearContext(contextId)` | Clear all entries in a context bucket |\n\n**LogStore:**\n\n| Method | Description |\n|---|---|\n| `log(entry)` | Write an invocation log |\n| `getLogs(filter?)` | Query logs with optional filters (agentId, sessionId, since, limit, offset) |\n| `getLog(id)` | Get a single log by ID |\n\n**Lifecycle:**\n\n| Method | Description |\n|---|---|\n| `close()` | Close the database connection |\n| `database` | Access the underlying `better-sqlite3` Database instance |\n\n## Schema\n\nThe store creates the following tables automatically:\n\n| Table | Description |\n|---|---|\n| `agents` | Agent definitions stored as JSON text |\n| `sessions` | Session metadata with timestamps |\n| `messages` | Conversation messages with JSON tool calls |\n| `context_entries` | Shared context entries between agents |\n| `invocation_logs` | Full invocation logs with token usage |\n| `schema_version` | Migration version tracking |\n\n**Indexes** on `messages(session_id)`, `context_entries(context_id)`, `invocation_logs(agent_id)`, `invocation_logs(session_id)`, and `invocation_logs(timestamp)`.\n\n## Performance Notes\n\n- **WAL mode** enabled by default — dramatically improves concurrent read performance\n- **Synchronous = NORMAL** — good balance of durability and speed\n- **Busy timeout = 5s** — handles brief write contention gracefully\n- **Foreign keys** enabled — cascading deletes keep data consistent\n- **Transactions** — session appends and deletes are wrapped in transactions for atomicity\n- **Synchronous API** — better-sqlite3 is synchronous under the hood, so no connection pool overhead\n\n### When to Use SQLite vs PostgreSQL\n\n| | SQLite | PostgreSQL |\n|---|---|---|\n| **Deployment** | Single server | Multi-server |\n| **Setup** | Zero config — just a file path | Requires a running database |\n| **Concurrent writes** | One writer at a time (WAL helps reads) | Full concurrent writes |\n| **Best for** | Dev, prototyping, single-instance production | Scaled production, multiple app instances |\n| **Package** | `@agent-runner/store-sqlite` | [`@agent-runner/store-postgres`](../store-postgres) |\n\n## Examples\n\n### Local Development\n\n```typescript\nimport { createRunner, defineAgent, JsonFileStore } from \"@agent-runner/core\";\nimport { SqliteStore } from \"@agent-runner/store-sqlite\";\n\n// Upgrade from JsonFileStore to SQLite — same API\nconst runner = createRunner({\n  store: new SqliteStore(\"./dev.db\"),\n});\n```\n\n### Testing with In-Memory Store\n\n```typescript\nimport { describe, it, expect, beforeEach } from \"vitest\";\nimport { createRunner } from \"@agent-runner/core\";\nimport { SqliteStore } from \"@agent-runner/store-sqlite\";\n\ndescribe(\"my agent\", () => {\n  let runner;\n\n  beforeEach(() => {\n    // Fresh database for every test — fast and isolated\n    runner = createRunner({\n      store: new SqliteStore(\":memory:\"),\n    });\n  });\n\n  it(\"persists sessions\", async () => {\n    // ...\n  });\n});\n```\n\n### With Studio\n\n```typescript\nimport { createRunner } from \"@agent-runner/core\";\nimport { SqliteStore } from \"@agent-runner/store-sqlite\";\nimport { createStudio } from \"@agent-runner/studio\";\n\nconst runner = createRunner({\n  store: new SqliteStore(\"./agents.db\"),\n});\n\nconst studio = await createStudio(runner, { port: 4000 });\nconsole.log(`Studio running at ${studio.url}`);\n```\n\n### Advanced: Direct Database Access\n\n```typescript\nconst store = new SqliteStore(\"./data.db\");\n\n// Run custom queries against the underlying database\nconst db = store.database;\nconst count = db.prepare(\"SELECT COUNT(*) as n FROM invocation_logs\").get();\nconsole.log(`Total invocations: ${count.n}`);\n```\n\n### Graceful Shutdown\n\n```typescript\nprocess.on(\"SIGTERM\", async () => {\n  await runner.shutdown();\n  store.close();\n  process.exit(0);\n});\n```\n\n## Related Packages\n\n| Package | Description |\n|---|---|\n| [`@agent-runner/core`](../core) | Core SDK — createRunner, agents, tools, stores |\n| [`@agent-runner/store-postgres`](../store-postgres) | PostgreSQL adapter for multi-server deployments |\n| [`@agent-runner/studio`](../studio) | Development UI |\n\n## Contributing\n\nSee the main [CONTRIBUTING.md](https://github.com/aparry3/agent-runner/blob/main/CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT © [Aaron Bidworthy](https://github.com/aparry3)\n","readmeFilename":"README.md"}