SDK Feedback: Local Development Mode

Summary

Introduce a local development mode to the Memori SDK that allows developers to build, test, and iterate on memory-powered applications without requiring API credentials or network connectivity. This mode would use an embedded SQLite database with simulated memory operations, enabling a true "zero-config" first experience.

The Problem

Today, developers must obtain API credentials before writing their first line of Memori code. This creates friction at the most critical moment in the developer journey: first contact. Based on common patterns in developer onboarding:

Credential barriers delay experimentation. Developers exploring Memori must sign up, wait for approval, and configure environment variables before seeing any working code.
Network dependency slows iteration. Every memory operation requires an API round-trip, making the feedback loop slower than it needs to be during active development.
CI/CD pipelines require secrets management. Running integration tests against the production API means managing credentials in CI environments and paying for API calls on every build.
Offline development is impossible. Developers on planes, trains, or spotty WiFi cannot work on Memori integrations.

Proposed Solution

Add a local=True parameter to the SDK client that activates an embedded, fully-functional memory layer backed by SQLite. The local mode should be API-compatible with production, so switching environments requires only a configuration change.

Developer Experience

from memori import MemoriClient

# Local development - no credentials needed
client = MemoriClient(local=True)

# Same API as production
client.memory.store(
    content="User prefers dark mode",
    attribution="user:123",
    type="preference"
)

memories = client.memory.recall(
    query="What are the user's UI preferences?",
    attribution="user:123"
)

# When ready for production, just change the config
# client = MemoriClient(api_key=os.environ["MEMORI_API_KEY"])
            

Core Capabilities

Embedded SQLite storage - Memory persists to ~/.memori/local.db by default, or an in-memory database for tests
Simulated embedding generation - Use a lightweight local embedding model (e.g., sentence-transformers) or deterministic hashing for semantic similarity
Full API parity - All memory operations (store, recall, forget, search) work identically to production
Debug tooling - Built-in memory inspector to see stored memories, their embeddings, and recall scores

Key Design Principle: Code written against local mode should work unchanged in production. The local mode is a development convenience, not a separate API.

Trade-offs Considered

Benefits

Zero-friction onboarding - developers can experiment immediately
Faster development iteration with local operations
Free CI/CD testing without API costs or secrets
Offline development capability
Deterministic tests without network flakiness
Lower barrier to contribution for open-source projects

Drawbacks

Additional code path to maintain and test
Local embeddings won't match production quality exactly
Risk of developers shipping local mode to production accidentally
Increases SDK package size with SQLite and embedding dependencies
May delay developers discovering production-specific issues

Mitigations

Production guard rails: Emit clear warnings when local mode is used, and fail loudly if local=True is detected in a production environment (e.g., via MEMORI_ENV=production)
Optional dependencies: Make local mode dependencies (SQLite driver, embedding model) optional installs via pip install memori[local]
Fidelity documentation: Clearly document which behaviors differ between local and production modes
Shared test suite: Run the same integration tests against both local and production modes to catch API drift

Alternatives Considered

1. Mock Client Only

Provide a MockMemoriClient that returns canned responses. Rejected because it doesn't allow meaningful development - developers can't build real memory-powered features against mocks.

2. Free Tier API Access

Offer a generous free tier with rate limits. Complements but doesn't replace local mode - developers still need credentials and network access, and free tier costs Memori infrastructure.

3. Docker-based Local Server

Ship a Docker image with a full Memori server. Rejected as too heavyweight - requires Docker, takes time to start, and adds operational complexity for simple use cases.

Success Metrics

Time to first working code: Target < 2 minutes from pip install to running memory operations
Adoption rate: Track percentage of new developers who start with local mode
Conversion rate: Measure how many local-mode users upgrade to production API keys within 7 days
CI usage: Monitor local mode usage in test environments via telemetry (opt-in)

Implementation Sketch

# memori/client.py
class MemoriClient:
    def __init__(self, api_key=None, instance=None, local=False):
        if local:
            self._backend = LocalBackend()
            self._warn_if_production()
        else:
            if not api_key:
                raise ConfigurationError("api_key required for production mode")
            self._backend = APIBackend(api_key, instance)

        # Same interface regardless of backend
        self.memory = MemoryService(self._backend)

# memori/backends/local.py
class LocalBackend:
    def __init__(self, db_path="~/.memori/local.db"):
        self.db = sqlite3.connect(db_path)
        self._init_schema()
        self.embedder = LocalEmbedder()  # lightweight model

    def store(self, content, attribution, type):
        embedding = self.embedder.encode(content)
        # Store in SQLite with embedding
        ...

    def recall(self, query, attribution, limit=10):
        query_embedding = self.embedder.encode(query)
        # Cosine similarity search in SQLite
        ...
            

Recommendation

Ship local development mode as a first-class feature of the SDK. The reduction in onboarding friction and the enablement of proper local testing workflows will accelerate developer adoption and improve the overall quality of Memori integrations. The trade-offs are manageable with the proposed mitigations, and the alternative approaches don't adequately solve the core problem.

Proposed timeline: Beta release within 4-6 weeks, targeting the Python SDK first, with TypeScript following based on adoption patterns.

SDK Feedback: Add Local Development Mode

Summary

The Problem

Proposed Solution

Developer Experience

Core Capabilities

Trade-offs Considered

Benefits

Drawbacks

Mitigations

Alternatives Considered

1. Mock Client Only

2. Free Tier API Access

3. Docker-based Local Server

Success Metrics

Implementation Sketch

Recommendation

Related Feedback